@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/skills/playable-art/scripts/import-gpt-art-sheets-v2.py

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""Mark and import GPT sheets via bg-remove + per-element segmentation + contain-fit."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from PIL import Image, ImageDraw
+
+from import_gpt_art_pipeline import (
+    Blob,
+    contain_center,
+    crop_digit_core,
+    filter_icon_noise,
+    find_blobs,
+    prepare_sheet_rgba,
+    project_root,
+    remove_chroma,
+    sort_blobs_reading_order,
+)
+
+ROOT = project_root()
+BLOCKING_SLICE_CLASSES = {"source_clipped", "slice_count_mismatch", "slice_safe_box_invalid"}
+
+
+@dataclass(frozen=True)
+class Entry:
+    name: str
+    out: str
+    size: tuple[int, int]
+    mode: str = "contain"
+
+
+@dataclass(frozen=True)
+class SheetSpec:
+    source: str
+    rows: int
+    entries: tuple[Entry, ...]
+    blob_pad: int = 12
+
+
+SPECS = (
+    SheetSpec(
+        "gpt-image-2-ui-sheet.png",
+        3,
+        (
+            Entry("ui_cta_btn", "ui/cta_btn.png", (820, 190)),
+            Entry("ui_finger", "ui/finger.png", (60, 90), "icon"),
+            Entry("ui_highlight", "ui/highlight.png", (80, 80), "icon"),
+            Entry("ui_panel_win", "ui/panel_win.png", (600, 360)),
+            Entry("ui_panel_lose", "ui/panel_lose.png", (600, 360)),
+            Entry("ui_boot_title", "ui/boot_title.png", (480, 80)),
+            Entry("ui_boot_loading", "ui/boot_loading.png", (280, 48)),
+        ),
+        blob_pad=16,
+    ),
+    SheetSpec(
+        "gpt-image-2-rewards-sheet.png",
+        2,
+        (
+            Entry("reward_combo_bg", "rewards/combo_bg.png", (300, 68)),
+            Entry("reward_gift", "rewards/gift.png", (128, 128), "icon"),
+            Entry("reward_toast_1", "rewards/toast_1.png", (600, 120)),
+            Entry("reward_toast_2", "rewards/toast_2.png", (600, 120)),
+            Entry("reward_toast_3", "rewards/toast_3.png", (600, 120)),
+            Entry("reward_bonus_1", "rewards/bonus_1.png", (640, 400)),
+            Entry("reward_bonus_2", "rewards/bonus_2.png", (640, 400)),
+            Entry("reward_bonus_3", "rewards/bonus_3.png", (640, 400)),
+        ),
+        blob_pad=14,
+    ),
+    SheetSpec(
+        "gpt-image-2-digits-sheet.png",
+        3,
+        tuple(
+            Entry(f"digit_{char}", f"digits/{path}.png", (48, 64), "digit")
+            for char, path in [
+                ("0", "0"), ("1", "1"), ("2", "2"), ("3", "3"), ("4", "4"),
+                ("5", "5"), ("6", "6"), ("7", "7"), ("8", "8"), ("9", "9"),
+                ("x", "x"), ("colon", "colon"), ("slash", "slash"),
+            ]
+        ),
+        blob_pad=8,
+    ),
+    SheetSpec(
+        "gpt-image-2-digits-glow-sheet.png",
+        2,
+        tuple(Entry(f"digit_{i}_glow", f"digits/{i}_glow.png", (48, 64), "digit") for i in range(10)),
+        blob_pad=8,
+    ),
+    SheetSpec(
+        "gpt-image-2-fx-sheet.png",
+        2,
+        (
+            Entry("particle_gold", "fx/particle_gold.png", (32, 32), "icon"),
+            Entry("particle_spark", "fx/particle_spark.png", (10, 36), "icon"),
+            Entry("particle_shard_lg", "fx/particle_shard_lg.png", (28, 36), "icon"),
+            Entry("particle_shard_md", "fx/particle_shard_md.png", (20, 26), "icon"),
+            Entry("particle_shard_sm", "fx/particle_shard_sm.png", (14, 18), "icon"),
+            Entry("tile_glow", "fx/tile_glow.png", (188, 228), "icon"),
+        ),
+        blob_pad=8,
+    ),
+)
+
+
+def _select_blobs(blobs: list[Blob], expected: int, rows: int) -> list[Blob]:
+    ordered = sort_blobs_reading_order(blobs, rows=rows)
+    if len(ordered) > expected:
+        print(f"  warn: found {len(ordered)} blobs, expected {expected}; dropping smallest fragments")
+        keep = sorted(ordered, key=lambda b: b.area, reverse=True)[:expected]
+        ordered = sort_blobs_reading_order(keep, rows=rows)
+    if len(ordered) < expected:
+        raise RuntimeError(f"expected {expected} elements, found {len(ordered)}")
+    return ordered
+
+
+def _process_sprite(image: Image.Image, entry: Entry) -> Image.Image:
+    if entry.mode == "icon":
+        image = filter_icon_noise(image)
+    if entry.mode == "digit":
+        image = crop_digit_core(image)
+    padding = 0 if entry.mode == "digit" else 4
+    return contain_center(image, entry.size, padding)
+
+
+def _box(blob: Blob) -> list[int]:
+    return [blob.left, blob.top, blob.right, blob.bottom]
+
+
+def _safe_box(blob: Blob, pad: int, image_size: tuple[int, int]) -> list[int]:
+    width, height = image_size
+    return [
+        max(0, blob.left - pad),
+        max(0, blob.top - pad),
+        min(width, blob.right + pad),
+        min(height, blob.bottom + pad),
+    ]
+
+
+def _margins(content_box: list[int], safe_box: list[int]) -> list[int]:
+    return [
+        content_box[0] - safe_box[0],
+        content_box[1] - safe_box[1],
+        safe_box[2] - content_box[2],
+        safe_box[3] - content_box[3],
+    ]
+
+
+def _mark_issues(content_box: list[int], safe_box: list[int], image_size: tuple[int, int], min_margin: int) -> list[dict[str, Any]]:
+    issues: list[dict[str, Any]] = []
+    margins = _margins(content_box, safe_box)
+    if min(margins) < min_margin:
+        issues.append(
+            {
+                "className": "slice_margin_tight",
+                "severity": "P2",
+                "message": f"safe slice margin below {min_margin}px",
+                "metrics": {"margins": margins, "minMargin": min_margin},
+            }
+        )
+    width, height = image_size
+    touches_edge = content_box[0] <= 0 or content_box[1] <= 0 or content_box[2] >= width or content_box[3] >= height
+    safe_clipped = safe_box[0] <= 0 or safe_box[1] <= 0 or safe_box[2] >= width or safe_box[3] >= height
+    if touches_edge or safe_clipped:
+        issues.append(
+            {
+                "className": "source_clipped",
+                "severity": "P1" if touches_edge else "P2",
+                "message": "content or safe slice reaches source image edge",
+                "metrics": {"touchesSourceEdge": touches_edge, "safeBoxClipped": safe_clipped},
+            }
+        )
+    return issues
+
+
+def _sheet_plan(spec: SheetSpec, selected: list[Blob], image_size: tuple[int, int], source_path: Path, root: Path) -> dict[str, Any]:
+    marks: list[dict[str, Any]] = []
+    for index, (entry, blob) in enumerate(zip(spec.entries, selected), start=1):
+        content_box = _box(blob)
+        safe_box = _safe_box(blob, spec.blob_pad, image_size)
+        margins = _margins(content_box, safe_box)
+        issues = _mark_issues(content_box, safe_box, image_size, min_margin=min(8, spec.blob_pad))
+        blocking = any(_is_blocking_issue(item) for item in issues)
+        mark = {
+            "id": f"{Path(spec.source).stem}:{entry.name}",
+            "index": index,
+            "entryName": entry.name,
+            "sourcePath": str(source_path.relative_to(root)),
+            "outputPath": str(Path("assets/images") / entry.out),
+            "mode": entry.mode,
+            "targetSize": list(entry.size),
+            "contentBox": content_box,
+            "safeSliceBox": safe_box,
+            "contentMarginInsideSafe": margins,
+            "touchesSourceEdge": min(content_box[0], content_box[1]) <= 0
+            or content_box[2] >= image_size[0]
+            or content_box[3] >= image_size[1],
+            "recommendedAction": "slice_from_safe_box",
+            "status": "fail" if blocking else "warn" if issues else "pass",
+            "blocking": blocking,
+            "issues": issues,
+        }
+        marks.append(mark)
+    blocking = any(mark.get("blocking") for mark in marks) or len(marks) != len(spec.entries)
+    return {
+        "source": spec.source,
+        "sourcePath": str(source_path.relative_to(root)),
+        "imageSize": list(image_size),
+        "expected": len(spec.entries),
+        "marked": len(marks),
+        "blobPad": spec.blob_pad,
+        "status": "fail" if blocking else "warn" if any(mark.get("issues") for mark in marks) else "pass",
+        "blocking": blocking,
+        "droppedFragments": [],
+        "marks": marks,
+    }
+
+
+def _is_blocking_issue(issue: dict[str, Any]) -> bool:
+    class_name = str(issue.get("className") or issue.get("class_name") or "")
+    severity = str(issue.get("severity") or "")
+    return class_name in BLOCKING_SLICE_CLASSES or severity in {"P0", "P1"}
+
+
+def _blocking_slice_issues(sheet_plan: dict[str, Any]) -> list[dict[str, Any]]:
+    blocking: list[dict[str, Any]] = []
+    for mark in sheet_plan.get("marks", []):
+        for issue in mark.get("issues", []):
+            if isinstance(issue, dict) and _is_blocking_issue(issue):
+                blocking.append(
+                    {
+                        **issue,
+                        "entryName": mark.get("entryName"),
+                        "sourcePath": mark.get("sourcePath"),
+                        "safeSliceBox": mark.get("safeSliceBox"),
+                    }
+                )
+    if int(sheet_plan.get("marked", 0)) != int(sheet_plan.get("expected", 0)):
+        blocking.append(
+            {
+                "className": "slice_count_mismatch",
+                "severity": "P1",
+                "message": f"expected {sheet_plan.get('expected')} slices, marked {sheet_plan.get('marked')}",
+                "sourcePath": sheet_plan.get("sourcePath"),
+            }
+        )
+    return blocking
+
+
+def _draw_box(draw: ImageDraw.ImageDraw, box: list[int], color: tuple[int, int, int], width: int) -> None:
+    for offset in range(width):
+        draw.rectangle(
+            (box[0] - offset, box[1] - offset, box[2] + offset, box[3] + offset),
+            outline=color,
+        )
+
+
+def render_slice_marks(source: Image.Image, sheet_plan: dict[str, Any], output_path: Path) -> None:
+    image = source.convert("RGBA")
+    overlay = Image.new("RGBA", image.size, (0, 0, 0, 0))
+    draw = ImageDraw.Draw(overlay)
+    for mark in sheet_plan["marks"]:
+        safe_box = mark["safeSliceBox"]
+        content_box = mark["contentBox"]
+        has_issue = bool(mark.get("issues"))
+        safe_color = (255, 193, 7) if has_issue else (0, 210, 120)
+        _draw_box(draw, safe_box, safe_color, 3)
+        _draw_box(draw, content_box, (255, 64, 64), 2)
+        label = f"{mark['index']:02d} {mark['entryName']}"
+        label_x = safe_box[0] + 4
+        label_y = max(0, safe_box[1] - 18)
+        text_w = max(120, len(label) * 7)
+        draw.rectangle((label_x - 2, label_y, label_x + text_w, label_y + 16), fill=(0, 0, 0, 180))
+        draw.text((label_x + 2, label_y + 2), label, fill=(255, 255, 255, 255))
+    marked = Image.alpha_composite(image, overlay)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    marked.save(output_path)
+
+
+def _write_plan(root: Path, sheets: list[dict[str, Any]], plan_path: Path) -> dict[str, Any]:
+    issue_count = sum(len(mark.get("issues", [])) for sheet in sheets for mark in sheet.get("marks", []))
+    fail_count = sum(1 for sheet in sheets for mark in sheet.get("marks", []) if mark.get("status") == "fail")
+    warn_count = sum(1 for sheet in sheets for mark in sheet.get("marks", []) if mark.get("status") == "warn")
+    mark_count = sum(len(sheet.get("marks", [])) for sheet in sheets)
+    plan = {
+        "schemaVersion": "playcraft.slice-plan.v1",
+        "generatedBy": "import-gpt-art-sheets-v2.py",
+        "root": str(root),
+        "status": "fail" if fail_count else "warn" if warn_count else "pass",
+        "blocking": fail_count > 0,
+        "summary": {
+            "sheets": len(sheets),
+            "marks": mark_count,
+            "issues": issue_count,
+            "fail": fail_count,
+            "warn": warn_count,
+        },
+        "sheets": sheets,
+    }
+    plan_path.parent.mkdir(parents=True, exist_ok=True)
+    plan_path.write_text(json.dumps(plan, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return plan
+
+
+def _display_path(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def import_spec(spec: SheetSpec, root: Path, mark_only: bool = False, allow_slice_issues: bool = False) -> dict[str, Any]:
+    ref = root / "assets" / "reference"
+    clean = ref / "cleaned"
+    images = root / "assets" / "images"
+    marks_dir = ref / "marked"
+    source = ref / spec.source
+    cache = clean / spec.source
+    had_cache = cache.exists()
+    sheet = prepare_sheet_rgba(source, cache)
+    bg_mode = "wavespeed" if os.getenv("WAVESPEED_API_KEY") and had_cache else "chroma"
+
+    alpha = sheet.getchannel("A")
+    blobs = find_blobs(alpha)
+    if len(blobs) < len(spec.entries):
+        print(f"  warn: {bg_mode} found {len(blobs)} blobs, retry chroma fallback")
+        sheet = remove_chroma(Image.open(source).convert("RGBA"))
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        sheet.save(cache)
+        bg_mode = "chroma-fallback"
+        blobs = find_blobs(sheet.getchannel("A"))
+
+    if not had_cache or bg_mode == "chroma-fallback":
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        sheet.save(cache)
+
+    selected = _select_blobs(blobs, len(spec.entries), spec.rows)
+    print(f"{spec.source}: bg={bg_mode} blobs={len(blobs)} use={len(selected)}")
+    plan = _sheet_plan(spec, selected, sheet.size, source, root)
+    render_slice_marks(Image.open(source).convert("RGBA"), plan, marks_dir / f"{Path(spec.source).stem}-slice-marks.png")
+    if mark_only:
+        return plan
+    blocking_issues = _blocking_slice_issues(plan)
+    if blocking_issues and not allow_slice_issues:
+        plan["status"] = "fail"
+        plan["blocking"] = True
+        plan["blockingIssues"] = blocking_issues
+        print(f"  block: {len(blocking_issues)} slice issue(s); inspect assets/reference/marked and slice-plan.json")
+        return plan
+
+    marks_by_name = {mark["entryName"]: mark for mark in plan["marks"]}
+    for entry in spec.entries:
+        safe_box = marks_by_name[entry.name]["safeSliceBox"]
+        sprite = _process_sprite(sheet.crop(tuple(safe_box)), entry)
+        out_path = images / entry.out
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        sprite.save(out_path)
+        print(f"  {entry.name} -> {entry.out} ({sprite.size[0]}x{sprite.size[1]})")
+    return plan
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=ROOT)
+    parser.add_argument("--mark-only", action="store_true", help="generate slice-plan and marked sheets without writing sliced assets")
+    parser.add_argument(
+        "--slice-plan",
+        type=Path,
+        default=None,
+        help="output path for slice-plan JSON; defaults to assets/reference/slice-plan.json",
+    )
+    parser.add_argument(
+        "--allow-slice-issues",
+        action="store_true",
+        help="debug escape hatch: write sprites even when blocking slice issues exist",
+    )
+    args = parser.parse_args()
+    root = args.root.resolve()
+    plan_path = args.slice_plan or (root / "assets" / "reference" / "slice-plan.json")
+    if not plan_path.is_absolute():
+        plan_path = root / plan_path
+
+    sheets: list[dict[str, Any]] = []
+    for spec in SPECS:
+        sheets.append(import_spec(spec, root, mark_only=args.mark_only, allow_slice_issues=args.allow_slice_issues))
+    plan = _write_plan(root, sheets, plan_path)
+    print(f"Slice plan: {_display_path(plan_path, root)} ({plan['summary']['marks']} marks, {plan['summary']['issues']} issues)")
+    if args.mark_only:
+        print("Done. Inspect assets/reference/marked before slicing, then run: npm run import:gpt-art")
+    elif plan.get("blocking") and not args.allow_slice_issues:
+        raise SystemExit("Blocked by slice-plan issues. Fix marked slices or rerun manually with --allow-slice-issues for debugging.")
+    else:
+        print("Done. Run: npm run build-atlas && npm run verify:ui:assets")
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/threejs/skills/playable-art/scripts/import-gpt-art-sheets.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""Import GPT-generated UI/reward/digit/fx sprite sheets into project assets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from PIL import Image
+
+from import_gpt_art_pipeline import project_root
+
+ROOT = project_root()
+REF = ROOT / "assets" / "reference"
+IMAGES = ROOT / "assets" / "images"
+MAGENTA = (255, 0, 255)
+
+
+@dataclass(frozen=True)
+class Entry:
+    name: str
+    out: str
+    size: tuple[int, int]
+    mode: str = "contain"
+
+
+@dataclass(frozen=True)
+class SheetSpec:
+    source: str
+    cols: int
+    rows: int
+    entries: tuple[Entry, ...]
+
+
+SPECS = (
+    SheetSpec(
+        "gpt-image-2-ui-sheet.png",
+        3,
+        3,
+        (
+            Entry("ui_cta_btn", "ui/cta_btn.png", (500, 80)),
+            Entry("ui_finger", "ui/finger.png", (60, 90), "icon"),
+            Entry("ui_highlight", "ui/highlight.png", (80, 80), "icon"),
+            Entry("ui_panel_win", "ui/panel_win.png", (600, 360)),
+            Entry("ui_panel_lose", "ui/panel_lose.png", (600, 360)),
+            Entry("ui_boot_title", "ui/boot_title.png", (480, 80)),
+            Entry("ui_boot_loading", "ui/boot_loading.png", (280, 48)),
+        ),
+    ),
+    SheetSpec(
+        "gpt-image-2-rewards-sheet.png",
+        4,
+        2,
+        (
+            Entry("reward_combo_bg", "rewards/combo_bg.png", (300, 68)),
+            Entry("reward_gift", "rewards/gift.png", (128, 128), "icon"),
+            Entry("reward_toast_1", "rewards/toast_1.png", (600, 120)),
+            Entry("reward_toast_2", "rewards/toast_2.png", (600, 120)),
+            Entry("reward_toast_3", "rewards/toast_3.png", (600, 120)),
+            Entry("reward_bonus_1", "rewards/bonus_1.png", (640, 400)),
+            Entry("reward_bonus_2", "rewards/bonus_2.png", (640, 400)),
+            Entry("reward_bonus_3", "rewards/bonus_3.png", (640, 400)),
+        ),
+    ),
+    SheetSpec(
+        "gpt-image-2-digits-sheet.png",
+        5,
+        3,
+        tuple(
+            Entry(f"digit_{char}", f"digits/{path}.png", (48, 64), "digit")
+            for char, path in [
+                ("0", "0"), ("1", "1"), ("2", "2"), ("3", "3"), ("4", "4"),
+                ("5", "5"), ("6", "6"), ("7", "7"), ("8", "8"), ("9", "9"),
+                ("x", "x"), ("colon", "colon"), ("slash", "slash"),
+            ]
+        ),
+    ),
+    SheetSpec(
+        "gpt-image-2-digits-glow-sheet.png",
+        5,
+        2,
+        tuple(Entry(f"digit_{i}_glow", f"digits/{i}_glow.png", (48, 64), "digit") for i in range(10)),
+    ),
+    SheetSpec(
+        "gpt-image-2-fx-sheet.png",
+        3,
+        2,
+        (
+            Entry("particle_gold", "fx/particle_gold.png", (32, 32), "icon"),
+            Entry("particle_spark", "fx/particle_spark.png", (10, 36), "icon"),
+            Entry("particle_shard_lg", "fx/particle_shard_lg.png", (28, 36), "icon"),
+            Entry("particle_shard_md", "fx/particle_shard_md.png", (20, 26), "icon"),
+            Entry("particle_shard_sm", "fx/particle_shard_sm.png", (14, 18), "icon"),
+            Entry("tile_glow", "fx/tile_glow.png", (188, 228), "icon"),
+        ),
+    ),
+)
+
+OVERRIDES = (
+    Entry("ui_finger", "ui/finger.png", (60, 90), "icon"),
+    Entry("reward_toast_1", "rewards/toast_1.png", (600, 120)),
+)
+
+OVERRIDE_SOURCES = {
+    "ui_finger": "gpt-image-2-ui-finger-down.png",
+    "reward_toast_1": "gpt-image-2-reward-toast-1.png",
+}
+
+
+def remove_chroma(image: Image.Image) -> Image.Image:
+    rgba = image.convert("RGBA")
+    pixels = rgba.load()
+    for y in range(rgba.height):
+        for x in range(rgba.width):
+            r, g, b, a = pixels[x, y]
+            is_key = abs(r - MAGENTA[0]) <= 42 and g <= 92 and abs(b - MAGENTA[2]) <= 42
+            is_fringe = r >= 150 and b >= 135 and g <= 105
+            if is_key or is_fringe:
+                pixels[x, y] = (255, 0, 255, 0)
+    return rgba
+
+
+def filter_components(image: Image.Image, min_area_ratio: float = 0.0015, keep_largest_only: bool = False) -> Image.Image:
+    """Remove tiny disconnected leftovers such as grid lines and chroma fringes."""
+    alpha = image.getchannel("A")
+    width, height = image.size
+    pixels = alpha.load()
+    visited = bytearray(width * height)
+    min_area = max(8, int(width * height * min_area_ratio))
+    keep = Image.new("L", image.size, 0)
+    keep_pixels = keep.load()
+
+    def idx(x: int, y: int) -> int:
+        return y * width + x
+
+    components: list[list[tuple[int, int]]] = []
+    for y in range(height):
+        for x in range(width):
+            start = idx(x, y)
+            if visited[start] or pixels[x, y] <= 8:
+                continue
+            stack = [(x, y)]
+            visited[start] = 1
+            comp: list[tuple[int, int]] = []
+            while stack:
+                cx, cy = stack.pop()
+                comp.append((cx, cy))
+                for nx, ny in ((cx + 1, cy), (cx - 1, cy), (cx, cy + 1), (cx, cy - 1)):
+                    if nx < 0 or ny < 0 or nx >= width or ny >= height:
+                        continue
+                    nidx = idx(nx, ny)
+                    if visited[nidx] or pixels[nx, ny] <= 8:
+                        continue
+                    visited[nidx] = 1
+                    stack.append((nx, ny))
+            components.append(comp)
+
+    if not components:
+        return image
+
+    largest_component = max(components, key=len)
+    largest = len(largest_component)
+    threshold = min(min_area, max(8, largest // 40))
+    for comp in components:
+        if keep_largest_only and comp is not largest_component:
+            continue
+        if len(comp) < threshold:
+            continue
+        for x, y in comp:
+            keep_pixels[x, y] = pixels[x, y]
+
+    out = image.copy()
+    out.putalpha(keep)
+    return out
+
+
+def crop_to_alpha(image: Image.Image, edge_pad: int = 2, threshold: int = 1) -> Image.Image:
+    alpha = image.getchannel("A")
+    if threshold > 1:
+        alpha = alpha.point(lambda p: 255 if p >= threshold else 0)
+    bbox = alpha.getbbox()
+    if not bbox:
+        return image
+    left, top, right, bottom = bbox
+    return image.crop((
+        max(0, left + edge_pad),
+        max(0, top + edge_pad),
+        min(image.width, right - edge_pad),
+        min(image.height, bottom - edge_pad),
+    ))
+
+
+def crop_digit_core(image: Image.Image) -> Image.Image:
+    alpha = image.getchannel("A")
+    strong = alpha.point(lambda p: 255 if p >= 132 else 0)
+    bbox = strong.getbbox() or alpha.getbbox()
+    if not bbox:
+        return image
+    left, top, right, bottom = bbox
+    margin_x = max(3, int((right - left) * 0.18))
+    margin_y = max(3, int((bottom - top) * 0.12))
+    return image.crop((
+        max(0, left - margin_x),
+        max(0, top - margin_y),
+        min(image.width, right + margin_x),
+        min(image.height, bottom + margin_y),
+    ))
+
+
+def fit(image: Image.Image, size: tuple[int, int], padding: int, mode: str) -> Image.Image:
+    max_w = max(1, size[0] - padding * 2)
+    max_h = max(1, size[1] - padding * 2)
+    scale = min(max_w / image.width, max_h / image.height)
+    new_size = (max(1, round(image.width * scale)), max(1, round(image.height * scale)))
+    resized = image.resize(new_size, Image.Resampling.LANCZOS)
+    out = Image.new("RGBA", size, (0, 0, 0, 0))
+    out.alpha_composite(resized, ((size[0] - new_size[0]) // 2, (size[1] - new_size[1]) // 2))
+    return out
+
+
+def import_spec(spec: SheetSpec) -> None:
+    source = REF / spec.source
+    sheet = Image.open(source).convert("RGBA")
+    cell_w = sheet.width // spec.cols
+    cell_h = sheet.height // spec.rows
+    if spec.source == "gpt-image-2-ui-sheet.png":
+        inset = max(44, min(cell_w, cell_h) // 24)
+    elif spec.source == "gpt-image-2-rewards-sheet.png":
+        inset = max(12, min(cell_w, cell_h) // 50)
+    else:
+        inset = max(4, min(cell_w, cell_h) // 70)
+
+    for index, entry in enumerate(spec.entries):
+        col = index % spec.cols
+        row = index // spec.cols
+        cell = sheet.crop((
+            col * cell_w + inset,
+            row * cell_h + inset,
+            (col + 1) * cell_w - inset,
+            (row + 1) * cell_h - inset,
+        ))
+        cleaned = filter_components(remove_chroma(cell), keep_largest_only=entry.mode == "icon")
+        if entry.mode == "digit":
+            content = crop_digit_core(crop_to_alpha(cleaned, edge_pad=0, threshold=12))
+        else:
+            content = crop_to_alpha(cleaned)
+        padding = 0 if entry.mode == "digit" else 4
+        sprite = fit(content, entry.size, padding, entry.mode)
+        out_path = IMAGES / entry.out
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        sprite.save(out_path)
+
+    print(f"Imported {len(spec.entries)} sprites from {source.name}")
+
+
+def import_overrides() -> None:
+    for entry in OVERRIDES:
+        source_name = OVERRIDE_SOURCES.get(entry.name)
+        if not source_name:
+            continue
+        source = REF / source_name
+        if not source.exists():
+            continue
+        image = Image.open(source).convert("RGBA")
+        content = crop_to_alpha(filter_components(remove_chroma(image)))
+        sprite = fit(content, entry.size, 4, entry.mode)
+        out_path = IMAGES / entry.out
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        sprite.save(out_path)
+        print(f"Imported override {entry.name} from {source.name}")
+
+
+def main() -> None:
+    for spec in SPECS:
+        import_spec(spec)
+    import_overrides()
+
+
+if __name__ == "__main__":
+    main()