@playcraft/cli 0.0.43 → 0.0.46

package/project-template/skills/playable-fx-decompose/scripts/generate-shard-debris.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""
+Regenerate shard_debris from wan_3 reference — ONE WaveSpeed gpt-image-2/edit call.
+
+Row 1 (f0-f3): front crack progression. Row 2 (f4-f7): quadrant modules.
+
+Usage:
+  python3 scripts/generate-shard-debris.py
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import shutil
+import sys
+import time
+from datetime import datetime
+from io import BytesIO
+from pathlib import Path
+
+import numpy as np
+import requests
+from PIL import Image
+
+ROOT = Path(__file__).resolve().parent.parent
+FX_DIR = ROOT / "assets" / "images" / "fx"
+REF_DIR = ROOT / "assets" / "reference"
+TILE_REF = ROOT / "assets" / "images" / "tiles" / "wan_3.png"
+BLANK_REF = ROOT / "assets" / "reference" / "tile_blank_face.png"
+API_BASE = "https://api.wavespeed.ai"
+
+EDIT_PROMPT = (
+    "Image 1 is a BLANK mahjong tile face — warm ivory/cream front, golden-amber side edge, "
+    "NO engraved characters, NO numbers, NO symbols. 2D mobile game look. "
+    "Create a NEW sprite sheet on perfectly flat pure magenta (#FF00FF) background. "
+    "Strict 2 rows x 4 columns, exactly 8 square cells, at least 100 pixels magenta gap between cells. "
+    "No dividers, no labels, no watermarks, no motion blur trails, no spark ribbons. "
+    "Row 1 — FRONT CRACK progression on the SAME blank ivory tile (front-facing, centered, same size): "
+    "Cell 0: intact blank ivory tile face (no characters). "
+    "Cell 1: same blank tile with thin hairline cracks on the ivory face only. "
+    "Cell 2: same blank tile, cracks spreading across the face, still one piece. "
+    "Cell 3: same blank tile, heavy cracks, about to break apart, still one connected piece. "
+    "Row 2 — SEPARATED QUADRANT MODULES from that blank tile (one ivory/brown shard per cell, slight 3D tilt ok): "
+    "Cell 4: top-left quadrant ivory shard, NO character strokes. "
+    "Cell 5: top-right quadrant shard. Cell 6: bottom-left. Cell 7: bottom-right. "
+    "Row 2 must NOT contain a whole tile — only broken pieces occupying at most 45% of each cell. "
+    "All 8 cells must use identical lighting and palette."
+)
+
+ASSET = {
+    "name": "shard_debris",
+    "cols": 4,
+    "rows": 2,
+    "crack_frames": 4,
+    "aspect_ratio": "1:1",
+    "resolution": "4k",
+    "quality": "low",
+}
+
+
+def load_env_key() -> str:
+    key = os.environ.get("WAVESPEED_API_KEY", "")
+    if key:
+        return key
+    env_path = ROOT / ".env"
+    if env_path.exists():
+        for line in env_path.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("WAVESPEED_API_KEY="):
+                return line.split("=", 1)[1].strip().strip('"').strip("'")
+    return ""
+
+
+def image_to_data_uri(path: Path) -> str:
+    raw = path.read_bytes()
+    b64 = base64.b64encode(raw).decode("ascii")
+    return f"data:image/png;base64,{b64}"
+
+
+def generate_edit(api_key: str, prompt: str, images: list[str], aspect_ratio: str, resolution: str, quality: str) -> str:
+    url = f"{API_BASE}/api/v3/openai/gpt-image-2/edit"
+    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+    payload = {
+        "prompt": prompt,
+        "images": images,
+        "aspect_ratio": aspect_ratio,
+        "resolution": resolution,
+        "quality": quality,
+        "output_format": "png",
+    }
+    r = requests.post(url, headers=headers, json=payload, timeout=120)
+    r.raise_for_status()
+    resp = r.json()
+    data = resp.get("data", resp)
+    pid = data.get("id", data.get("prediction_id", resp.get("id", "")))
+    if not pid:
+        raise RuntimeError(f"No prediction id: {json.dumps(resp)[:500]}")
+    return pid
+
+
+def poll_result(api_key: str, pid: str) -> str:
+    result_url = f"{API_BASE}/api/v3/predictions/{pid}/result"
+    for attempt in range(120):
+        time.sleep(3)
+        r = requests.get(result_url, headers={"Authorization": f"Bearer {api_key}"}, timeout=30)
+        r.raise_for_status()
+        res = r.json()
+        data = res.get("data", res)
+        status = data.get("status", "")
+        print(f"  poll {attempt + 1}: {status}")
+        if status in ("succeeded", "completed", "success"):
+            outputs = data.get("outputs", [])
+            if outputs:
+                out = outputs[0]
+                return out if isinstance(out, str) else out.get("url", out.get("image", ""))
+            return data.get("output", data.get("url", ""))
+        if status in ("failed", "error", "canceled"):
+            raise RuntimeError(f"Generation failed: {json.dumps(res)[:500]}")
+    raise RuntimeError("Poll timeout")
+
+
+def remove_chroma(img: Image.Image) -> Image.Image:
+    arr = np.array(img.convert("RGBA"))
+    r, g, b = arr[:, :, 0], arr[:, :, 1], arr[:, :, 2]
+    is_key = (np.abs(r.astype(int) - 255) <= 52) & (g <= 100) & (np.abs(b.astype(int) - 255) <= 52)
+    is_fringe = (r >= 150) & (b >= 135) & (g <= 110)
+    mask = is_key | is_fringe
+    arr[mask, :3] = 0
+    arr[mask, 3] = 0
+    return Image.fromarray(arr)
+
+
+def content_bbox(alpha: np.ndarray, threshold: int = 32) -> tuple[int, int, int, int] | None:
+    ys, xs = np.where(alpha > threshold)
+    if len(xs) == 0:
+        return None
+    return int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1
+
+
+def crop_content(img: Image.Image, pad: int = 8) -> Image.Image | None:
+    rgba = remove_chroma(img)
+    arr = np.array(rgba)
+    bbox = content_bbox(arr[:, :, 3])
+    if bbox is None:
+        return None
+    x0, y0, x1, y1 = bbox
+    x0 = max(0, x0 - pad)
+    y0 = max(0, y0 - pad)
+    x1 = min(arr.shape[1], x1 + pad)
+    y1 = min(arr.shape[0], y1 + pad)
+    return Image.fromarray(arr).crop((x0, y0, x1, y1))
+
+
+def repack_crack_frames(frames: list[Image.Image], pad: int = 16) -> list[Image.Image]:
+    """Center crack frames on a shared canvas for stable frame animation."""
+    if not frames:
+        return frames
+    max_w = max(im.size[0] for im in frames)
+    max_h = max(im.size[1] for im in frames)
+    out_w = max_w + 2 * pad
+    out_h = max_h + 2 * pad
+    packed: list[Image.Image] = []
+    for im in frames:
+        canvas = Image.new("RGBA", (out_w, out_h), (0, 0, 0, 0))
+        px = (out_w - im.size[0]) // 2
+        py = (out_h - im.size[1]) // 2
+        canvas.alpha_composite(im, (px, py))
+        packed.append(canvas)
+    return packed
+
+
+def slice_sheet(raw_path: Path, cols: int, rows: int) -> list[Image.Image]:
+    img = Image.open(raw_path).convert("RGBA")
+    w, h = img.size
+    fw, fh = w // cols, h // rows
+    cells: list[Image.Image] = []
+    for row in range(rows):
+        for col in range(cols):
+            cells.append(img.crop((col * fw, row * fh, (col + 1) * fw, (row + 1) * fh)))
+    return cells
+
+
+def backup_existing() -> None:
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = REF_DIR / f"shard_debris-backup-{stamp}"
+    backup.mkdir(parents=True, exist_ok=True)
+    for path in sorted(FX_DIR.glob("shard_debris_frame*.png")):
+        shutil.copy(path, backup / path.name)
+    raw = ROOT / "assets" / "images" / "shard_debris_raw.png"
+    if raw.exists():
+        shutil.copy(raw, backup / raw.name)
+    print(f"[backup] -> {backup.relative_to(ROOT)}")
+
+
+def save_frames(crack: list[Image.Image], modules: list[Image.Image], name: str) -> list[Path]:
+    out_paths: list[Path] = []
+    idx = 0
+    for im in crack + modules:
+        out_path = FX_DIR / f"{name}_frame{idx:02d}.png"
+        im.save(out_path)
+        print(f"  frame{idx:02d}: {im.size[0]}x{im.size[1]}")
+        out_paths.append(out_path)
+        idx += 1
+    return out_paths
+
+
+def main() -> None:
+    api_key = load_env_key()
+    if not api_key:
+        print("ERROR: WAVESPEED_API_KEY not found", file=sys.stderr)
+        sys.exit(1)
+    if not TILE_REF.exists():
+        print(f"ERROR: missing reference tile {TILE_REF}", file=sys.stderr)
+        sys.exit(1)
+
+    edit_ref = BLANK_REF if BLANK_REF.exists() else TILE_REF
+    if edit_ref == TILE_REF:
+        print("[generate-shard-debris] WARN: tile_blank_face missing — run build-blank-tile-crack.py after slice")
+
+    FX_DIR.mkdir(parents=True, exist_ok=True)
+    REF_DIR.mkdir(parents=True, exist_ok=True)
+    backup_existing()
+
+    ref_copy = REF_DIR / f"shard_debris_ref_blank_{datetime.now().strftime('%Y%m%d-%H%M%S')}.png"
+    shutil.copy(edit_ref, ref_copy)
+    print(f"[ref] {ref_copy.relative_to(ROOT)}")
+
+    print("[generate-shard-debris] gpt-image-2/edit (1 call)...")
+    pid = generate_edit(
+        api_key,
+        EDIT_PROMPT,
+        [image_to_data_uri(edit_ref)],
+        ASSET["aspect_ratio"],
+        ASSET["resolution"],
+        ASSET["quality"],
+    )
+    print(f"  task id: {pid}")
+
+    url = poll_result(api_key, pid)
+    raw_path = ROOT / "assets" / "images" / "shard_debris_raw.png"
+    r = requests.get(url, timeout=120)
+    r.raise_for_status()
+    raw_path.write_bytes(r.content)
+    sheet_copy = REF_DIR / f"shard_debris_sheet_{datetime.now().strftime('%Y%m%d-%H%M%S')}.png"
+    shutil.copy(raw_path, sheet_copy)
+    print(f"  raw: {raw_path} ({raw_path.stat().st_size} bytes)")
+
+    cells = slice_sheet(raw_path, ASSET["cols"], ASSET["rows"])
+    crack_raw: list[Image.Image] = []
+    modules_raw: list[Image.Image] = []
+    for i, cell in enumerate(cells):
+        cropped = crop_content(cell)
+        if cropped is None:
+            cropped = Image.new("RGBA", (64, 64), (0, 0, 0, 0))
+            print(f"  [WARN] cell {i}: empty")
+        if i < ASSET["crack_frames"]:
+            crack_raw.append(cropped)
+        else:
+            modules_raw.append(cropped)
+
+    crack = repack_crack_frames(crack_raw)
+    frames = save_frames(crack, modules_raw, ASSET["name"])
+    print(f"[generate-shard-debris] sliced — {len(frames)} frames")
+
+    build_script = ROOT / "scripts" / "build-blank-tile-crack.py"
+    if build_script.exists():
+        import subprocess
+        print("[generate-shard-debris] building blank crack overlays...")
+        subprocess.run([sys.executable, str(build_script)], check=True)
+    print("[generate-shard-debris] done")
+
+
+if __name__ == "__main__":
+    main()

package/project-template/skills/playable-fx-peak/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: playable-fx-peak
+description: >-
+  Frame ADD FX repack + anchor gate for playables. Agent MUST run ensure-project,
+  then repack/validate scripts, then playground clean:frame record. Use when user
+  asks to fix burst/ring/ray clip, drift, vignette, or peak footprint in MP4.
+  User never runs repack manually.
+---
+
+# Playable Frame FX Peak Pipeline
+
+> **用户**：「用 peak pipeline 优化 match_burst / combo_ring / victory_ray」  
+> **Agent**：ensure-project → repack → anchor gate → catalog → clean 录屏。
+
+---
+
+## Agent 入口
+
+### 0. 自举
+
+```bash
+npm run ensure:project
+pip install -r ../skills/playable-fx-peak/requirements.txt
+```
+
+### 1. Repack（有 `_raw.png` 时）
+
+```bash
+npm run repack:frames -- --raw assets/images/fx/<name>_raw.png --name <name> \
+  --cols 6 --report validate/focus/frame/<name>-repack.json
+```
+
+### 2. Anchor gate（必须 PASS 再录屏）
+
+```bash
+npm run validate:frame-anchors -- 'assets/images/fx/<name>_frame*.png' \
+  --json validate/focus/frame/<name>-anchor.json
+```
+
+FAIL → 调 repack 参数或重出 sheet，禁止跳过 gate 直接改 game。
+
+### 3. 更新 catalog + runtime
+
+`playground/vfx-catalog.json`：`peakFrame`, `peakIndex`, `frameCanvas`。  
+`game/gameplay/frame-fx.js` 使用 peak footprint（见本 skill 下文）。
+
+### 4. Clean 录屏验收
+
+```bash
+npm run playground -- record clean:frame:<name> --headed
+```
+
+### 5. 卷到 G
+
+`integration:EVENT:match-once` 或 video-validate-loop 整片 MP4。
+
+---
+
+---
+
+## GPT 出图与合成 A/B
+
+> 原 `playable-gpt-fx-frame-animation` 已并入本节（repack 以下仍用本 skill 脚本）。
+
+1. **GPT-Image-2 无真透明** — 后处理必选：alpha 通道 **或** 黑底 + ADD 运行时语义
+2. **效果定管线** — 同 raw sheet A/B：`bg removal + NORMAL/ADD` vs `黑底 + ADD`；**headed 录屏定赢家**，不按 FX 类型标签先验
+3. **切片 ≠ 合成** — 邻帧鬼影 → 间距 + edge fade；halo 被切短 → remover 吃掉 glow → 试黑底+ADD
+
+| 录屏现象     | 优先尝试                |
+| ------------ | ----------------------- |
+| 光晕外圈断掉 | 黑底 + ADD              |
+| 竖缝/鬼影    | repack 间距 + edge fade |
+| 金边发绿     | 换黑底或弱抠图；A/B     |
+
+**出图 prompt 要点**：`pure black (#000000)`、`generous spacing`、`frames must NOT touch`。一 sheet 一特效。切格后 **立即** edge fade（两条路径都要）。
+
+```js
+sprite.setBlendMode(Phaser.BlendModes.ADD); // soft glow 常胜路径
+```
+
+## 核心原则（test12→test13 教训）
+
+1. **raw sheet 好看 ≠ 单帧可用** — 机械等分切格会在 cell 边界产生硬直边；整条 strip 连续，单格可能 x=0/x=639 贴边。
+2. **最大帧定盘** — peak frame（bbox 面积最大）定义 canvas；**全序列 union 半宽/半高** 定 canvas 边长，不是固定 640×640。
+3. **后处理与播放是两层** — PNG anchor 对齐后，Phaser `setScale` + scale tween 仍会让框随纹理跳；播放必须用 **peak footprint**（`setDisplaySize` + `animationupdate` 重锁）。
+4. **edge fade 不是万能** — 只治邻帧鬼影；margin ≈ fade 宽度时会吃进内容。fade 必须 **按 content margin 自适应**。
+5. **Video Validate 不会自动发现 anchor 问题** — `verify:ui`、edge 亮度 0、L1 sweep「录屏成功」都不够；必须 `validate-frame-anchors.py` + clean harness 黑底录屏。
+
+## 一句话流程
+
+```
+GPT raw sheet
+  → repack-frame-sequence.py（normalize_cell → isolate → union canvas → flatten）
+  → validate-frame-anchors.py（gate）
+  → 写 catalog：peakFrame / peakIndex / frameCanvas
+  → FrameFx.spawn（peak displaySize 锁定）
+  → focus-lab 黑底录屏验收
+```
+
+## Step 1: Repack（必须）
+
+```bash
+cd testN   # playable 工程根
+
+python3 ../skills/playable-fx-peak/scripts/repack-frame-sequence.py \
+  --raw assets/images/fx/<name>_raw.png \
+  --name <name> \
+  --cols 6 --rows 1 \
+  --lum-threshold 38 \
+  --report validate/focus/frame/<name>-repack.json
+```
+
+脚本做什么：
+
+| 阶段                | 作用                                              |
+| ------------------- | ------------------------------------------------- |
+| `normalize_cell`    | 内容碰 cell 边 → 缩进 safe zone，把切格硬边往里推 |
+| `isolate_subject`   | 最大连通域 + flatten 灰 vignette                  |
+| `canvas_from_union` | 所有帧 centroid 贴中心时所需最大半宽/半高 + pad   |
+| `fade_for_canvas`   | 仅当 margin 足够才 fade，避免裁切                 |
+
+**禁止**：机械切格 → 仅 edge fade → 直接进游戏。
+
+## Step 2: 像素 Gate（必须）
+
+```bash
+python3 ../skills/playable-fx-peak/scripts/validate-frame-anchors.py 'assets/images/fx/<name>_frame*.png' \
+  --json validate/focus/frame/<name>-anchor.json
+```
+
+FAIL 任一即不得合并：
+
+- `drift_px` > 12（质心偏离 canvas 中心）
+- L/R 亮像素比 > 1.6（双主体 / 邻帧串格）
+- `edge_touch`（内容距边 < 10px）
+- `grey_px` > 500（GPT vignette 灰窗未清）
+
+## Step 3: Catalog 元数据（必须）
+
+repack 报告含 `peak_frame`、`frameCanvas`。写入 `playground/vfx-catalog.json`：
+
+```json
+{
+  "id": "match_burst_v2",
+  "peakIndex": 3,
+  "peakFrame": "fx_match_burst_v2_f3",
+  "frameCanvas": [468, 468],
+  "scale": 0.45,
+  "blendMode": "ADD"
+}
+```
+
+`peakFrame` key 须与 `asset-manifest.js` 一致。
+
+## Step 4: 播放锁定（必须）
+
+使用 `game/gameplay/frame-fx.js` — **禁止**对帧动画仅用 `setScale` + scale tween。
+
+```js
+var sprite = FrameFx.spawn(scene, x, y, spec, {
+  scale: spec.scale,
+  blendModeName: spec.blendMode,
+  animKey: spec.animKey,
+  onComplete: function () {
+    if (sprite.active) sprite.destroy();
+  },
+});
+```
+
+要点：
+
+- `setOrigin(0.5, 0.5)`
+- `setDisplaySize(frameCanvas.w * scale, frameCanvas.h * scale)` — 以 **peak canvas** 为舞台
+- `animationupdate` 里重锁 displaySize
+- 可 fade alpha；**不要** scale tween（会让「框」在动，不是「光」在扩）
+
+Clean lab：`focus-lab/frame.html?spec=<id>&capture=1`，capture 模式纯黑底、无 scale tween。
+
+## Step 5: 录屏验收
+
+```bash
+node scripts/playground.mjs record clean:frame:<id> --duration=6000 --warmup=1000
+```
+
+通过标准（效果语言）：
+
+- [ ] 爆发中心全程不漂移
+- [ ] 无上下/左右直边裁切（尤其 peak 帧）
+- [ ] 无灰窗/双窗口闪动
+- [ ] 小帧在大盘中心 **原位变大变小**，不是 sprite 框缩放
+
+## 常见现象 → 根因
+
+| 现象                      | 根因                   | 修复                                   |
+| ------------------------- | ---------------------- | -------------------------------------- |
+| raw 好、PNG 有左右直边    | 切格贴 cell 边         | `normalize_cell` + 加大 prompt spacing |
+| 数值 drift PASS、录屏仍跳 | Phaser 按纹理改框      | `FrameFx.lockFootprint`                |
+| 棕底上见方框              | grey vignette + 非黑底 | flatten + ADD + 黑底 harness           |
+| 双团并排                  | 邻帧串格 / 双主体      | repack 最大 blob + 重出 sheet          |
+| L1 11/11 仍 FAIL 视觉     | 无 anchor 脚本 gate    | 本 skill Step 2                        |
+
+## GPT Prompt 约束（出图侧）
+
+与 repack 配套，写进 prompt：
+
+- 每 cell **一个** burst，禁止 side-by-side / comparison
+- burst ≤ 55% cell 宽，**不得碰 cell 边**
+- 禁止 vignette / diamond mask / grey rounded rect
+- **同一 impact 中心** in-place 演变，禁止 spiral 漂移构图
+- `generous spacing`，至少 120px 间隙
+
+## 相关文件（test12）
+
+| 文件                                                           | 职责               |
+| -------------------------------------------------------------- | ------------------ |
+| `scripts/repack-frame-sequence.py`                             | 后处理主流程       |
+| `../skills/playable-fx-peak/scripts/validate-frame-anchors.py` | 像素 gate          |
+| `game/gameplay/frame-fx.js`                                    | peak 播放锁定      |
+| `focus-lab/harness/frame-lab-scene.js`                         | clean 录屏 harness |
+| `playground/vfx-catalog.json`                                  | spec 元数据        |
+
+## 实验记录
+
+### test12 — match_burst_v2（2026-06-11）
+
+- 仅切格+fade：双窗口、漂移、左硬切 — **P0**
+- 固定 640 canvas + centroid：改善但仍裁切 — peak 应定盘，union 定边
+- `normalize_cell` + union canvas + `FrameFx`：anchor drift < 1px，录屏中心稳定
+- Video Validate 未早发现问题：缺 anchor 脚本 + focus stub 未填实 + 无 peakFootprint 播放层
+
+更多脚本参数见 [reference.md](reference.md)。
+
+## Related Skills
+
+- [playable-fx-decompose](../playable-fx-decompose/SKILL.md) — 破碎 decompose（NORMAL）
+- [playable-validate](../playable-validate/SKILL.md) — 录屏闭环
+- [playable-art](../playable-art/SKILL.md) — 静态 UI sheet

package/project-template/skills/playable-fx-peak/requirements.txt

@@ -0,0 +1,2 @@
+numpy>=1.24
+Pillow>=10.0

package/project-template/skills/playable-fx-peak/scripts/fix-frame-edges.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+Fix edge leakage in sprite sheet frames by applying edge fade masks.
+Run this after slicing sprite sheets to clean up adjacent-frame bleed.
+"""
+
+from PIL import Image
+import numpy as np
+import glob
+import os
+
+def apply_edge_fade(img_path, output_path, fade_px=50):
+    """Apply a fade-to-black mask on all edges of the image."""
+    img = Image.open(img_path).convert('RGBA')
+    w, h = img.size
+    arr = np.array(img)
+
+    # Create a mask (0 = transparent, 255 = opaque)
+    mask = np.ones((h, w), dtype=np.float32)
+
+    # Horizontal fade (left and right edges)
+    for x in range(min(fade_px, w // 2)):
+        alpha = x / fade_px
+        mask[:, x] = np.minimum(mask[:, x], alpha)
+        mask[:, w - 1 - x] = np.minimum(mask[:, w - 1 - x], alpha)
+
+    # Vertical fade (top and bottom edges)
+    for y in range(min(fade_px, h // 2)):
+        alpha = y / fade_px
+        mask[y, :] = np.minimum(mask[y, :], alpha)
+        mask[h - 1 - y, :] = np.minimum(mask[h - 1 - y, :], alpha)
+
+    # Apply mask to alpha channel
+    # If the image already has an alpha channel, multiply it with the mask
+    # Otherwise, use the mask as the alpha (but since background is black,
+    # we need to handle it carefully)
+    old_alpha = arr[:, :, 3].astype(np.float32) / 255.0
+    new_alpha = (old_alpha * mask * 255).astype(np.uint8)
+    arr[:, :, 3] = new_alpha
+
+    # Also darken RGB by the mask to ensure black edges stay black
+    for c in range(3):
+        arr[:, :, c] = (arr[:, :, c].astype(np.float32) * mask).astype(np.uint8)
+
+    result = Image.fromarray(arr)
+    result.save(output_path)
+    print(f'  {os.path.basename(output_path)}: applied {fade_px}px edge fade')
+
+def process_frames(pattern, fade_px):
+    files = sorted(glob.glob(pattern))
+    if not files:
+        print(f'No files found for: {pattern}')
+        return
+    print(f'Processing {len(files)} frames with {fade_px}px fade...')
+    for f in files:
+        apply_edge_fade(f, f, fade_px)
+
+if __name__ == '__main__':
+    base_dir = os.path.join(os.path.dirname(__file__), '..', 'assets', 'images', 'fx')
+
+    # match_burst: 640x1280, severe leakage on both sides + top/bottom on large frames
+    process_frames(os.path.join(base_dir, 'match_burst_frame*.png'), fade_px=50)
+
+    # combo_ring: 768x1920, moderate leakage on sides
+    process_frames(os.path.join(base_dir, 'combo_ring_frame*.png'), fade_px=60)
+
+    # star_sparkle: minimal leakage, skip
+    # victory_ray: no leakage, skip
+
+    print('Done!')