@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/agents/refs/ta-tools-reference.md

@@ -0,0 +1,111 @@
+# TA Tools Reference
+
+> Read by Technical Artist before starting any pipeline work. Contains full command reference for all TA tools.
+
+## AI Generation
+
+| Command                             | Purpose                             | Key Params                                                             |
+| ----------------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
+| `playcraft tools generate-image`    | Generate image with style reference | `--prompt`, `--output`, `--reference-image` (up to 8), `--image-model` |
+| `playcraft tools list-image-models` | List available models               | `--json`                                                               |
+| `playcraft tools search-image`      | Search reference images             | `--query`, `--count`, `--json`                                         |
+| `playcraft tools research`          | Research style/technical params     | `--query`, `--focus visual\|code`, `--json`                            |
+
+## 3D Model Pipeline
+
+| Command                          | Purpose                                   | Key Params                                             |
+| -------------------------------- | ----------------------------------------- | ------------------------------------------------------ |
+| `playcraft tools generate-3d`    | AI text-to-3D / image-to-3D (HunyuanTo3D) | `--prompt`, `--input`, `--output model.glb`, `--model` |
+| `playcraft tools list-3d-models` | List available 3D generation configs      | `--json`                                               |
+| `playcraft 3d list-models`       | List bundled white model primitives       | —                                                      |
+| `playcraft 3d info <model>`      | Show vertex/face/UV details               | `--json`                                               |
+| `playcraft 3d apply-texture`     | Apply image texture to white model        | `--model`, `--texture`, `--output`, `--color`          |
+| `playcraft 3d convert`           | Convert GLB ↔ GLTF                        | `--input`, `--output`                                  |
+| `playcraft 3d optimize`          | Compress GLB (texture resize, dedup)      | `--input`, `--output`, `--texture-size 512`            |
+
+## Sprite Sheet Pipeline
+
+| Command                        | Purpose                         | Key Params                                                                                                                        |
+| ------------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `playcraft image sprite-split` | Split sprite sheet into frames  | `--input`, `--output-dir`, `--auto-detect` OR `--rows --columns --frame-width --frame-height`                                     |
+| `playcraft image sprite-sheet` | Merge frames into sprite sheet  | `--inputs`, `--output`, `--columns`, `--cell-width`, `--cell-height`, `--padding`                                                 |
+| `playcraft image animate`      | Generate animation sprite sheet | `--input`, `--preset spin\|bounce\|pulse\|shake\|float\|blink\|swing\|wobble\|flip`, `--frames 8`, `--output`                     |
+| `playcraft image list-vfx`     | List bundled VFX sprite presets | `--json`                                                                                                                          |
+| `playcraft image use-vfx`      | Copy VFX preset to project      | `--preset explosion_small\|sparkle\|confetti\|starburst\|smoke\|glow\|impact_ring\|coin_collect`, `--output`, `--tint`, `--scale` |
+
+## Concept Art Extraction (SAM3 Segmentation)
+
+> **Use this BEFORE AI generation** — extracting from confirmed concept art is faster and more style-consistent.
+
+| Command                   | Purpose                                                      | Key Params                                                                                                              |
+| ------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `playcraft image segment` | SAM3 semantic segmentation: text prompt → mask + RGBA cutout | `--input`, `--text "<description>"`, `--extract-rgba` (transparent cutout), `--output-dir`, `--prompts '[...]'` (batch) |
+
+**Workflow**:
+
+```bash
+# Single element extraction
+playcraft image segment \
+  --input assets/images/concept/option_a.jpg \
+  --text "playing card spade ace" \
+  --extract-rgba \
+  --output-dir ta-workspace/tmp/
+
+# Batch extraction from same concept art
+playcraft image segment \
+  --input assets/images/concept/option_a.jpg \
+  --prompts '[{"text":"score display"},{"text":"timer icon"},{"text":"combo banner"}]' \
+  --extract-rgba \
+  --output-dir ta-workspace/tmp/ui-seg/
+
+# Then: resize extracted elements to assetSpec dimensions
+playcraft image resize --input ta-workspace/tmp/card_extracted.png \
+  --output assets/images/tiles/card_spade_A.png \
+  --width 140 --height 196
+```
+
+**Notes**:
+
+- Cold start ≈ 15s; subsequent calls fast
+- If extracted quality is insufficient → fall back to AI generation with the concept art as `--reference-image`
+- `--extract-rgba` produces transparent PNG directly (no separate `remove-background` needed)
+
+## Image Processing
+
+| Category     | Commands                                                   |
+| ------------ | ---------------------------------------------------------- |
+| Geometry     | `resize` / `crop` / `rotate` / `flip` / `pad` / `trim`     |
+| Format       | `convert` (png/jpg/webp/avif)                              |
+| Filters      | `grayscale` / `blur` / `tint` / `negate` / `pixelate`      |
+| Composite    | `overlay` (layer images)                                   |
+| Background   | `remove-background` (floodfill or --method ai)             |
+| Segmentation | `segment` (SAM3, text-prompt extraction from scene images) |
+| Info         | `info` (dimensions, format, size)                          |
+
+## Smart Segmentation (SAM3)
+
+| Command                   | Purpose                                               | Key Params                                                                   |
+| ------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `playcraft image segment` | AI semantic segmentation (SAM3), produces mask + rgba | `--input`, `--text` OR `--boxes`, `--output-dir`, `--threshold`, `--no-rgba` |
+
+> For full guide (text prompt / box mode / threshold tuning / mask compositing workflows), **invoke the `playcraft-masking` skill**.
+
+## Batch Processing
+
+| Command                    | Purpose                                                       | Key Params                                                                  |
+| -------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `playcraft image batch`    | Declarative multi-step batch on a directory                   | `--input-dir`, `--output-dir`, `--steps`, `--parallel N`, `--skip-existing` |
+| `playcraft image pipeline` | YAML/JSON config pipeline with optional sprite-sheet assembly | `--config <yaml/json>`, `--dry-run`                                         |
+
+> For decision tree (Node.js script vs batch vs pipeline), step syntax, and known limitations, **invoke the `playcraft-batch-pipeline` skill**.
+
+## Audio Processing
+
+| Command                    | Purpose                |
+| -------------------------- | ---------------------- |
+| `playcraft audio compress` | Reduce file size       |
+| `playcraft audio trim`     | Cut to target duration |
+| `playcraft audio loop`     | Make seamless loop     |
+| `playcraft audio fade`     | Add fade in/out        |
+| `playcraft audio convert`  | Change format          |
+| `playcraft audio info`     | Check metadata         |

package/project-template/.claude/agents/refs/ta-vfx-preset-catalog.md

@@ -0,0 +1,365 @@
+> 本文件是 VFX/动画预设的完整目录与配方参考。选型决策见 `playcraft-vfx-animation` skill。
+
+# VFX/动画预设完整目录与配方
+
+---
+
+## 1. VFX 预设完整详解（8 个）
+
+| 预设名            | 帧数 | 列数 | 体积  | 适用游戏事件                   | 典型颜色          |
+| ----------------- | ---- | ---- | ----- | ------------------------------ | ----------------- |
+| `explosion_small` | 8    | 4    | ~30KB | 消除、方块击破、碰撞           | 橙红黄渐变        |
+| `sparkle`         | 6    | 3    | ~15KB | 得分、道具收集、奖励获得       | 金黄/白色闪光     |
+| `confetti`        | 12   | 4    | ~25KB | 关卡完成、大胜利、解锁         | 多彩纸片          |
+| `starburst`       | 8    | 4    | ~20KB | 奖励显示、连击触发、特殊技能   | 金色放射          |
+| `smoke`           | 8    | 4    | ~20KB | 元素消失、角色冲刺、撞击后尘   | 白/灰烟雾         |
+| `glow`            | 6    | 3    | ~10KB | 元素高亮、被选中状态、增益效果 | 发光环（可 tint） |
+| `impact_ring`     | 6    | 3    | ~15KB | 物体落地、受击反馈、点击反馈   | 白色扩散环        |
+| `coin_collect`    | 8    | 4    | ~20KB | 金币拾取、货币奖励             | 金黄闪光          |
+
+### explosion_small — 小型爆炸
+
+- **动画感**：中心爆发 -> 碎片扩散 -> 消散，8 帧循环
+- **最佳用途**：Match-3 消除时的元素爆炸效果；方块游戏砖块击破
+- **Tint 建议**：橙红系（默认），蓝紫系适合冰系技能
+- **Scale 建议**：1.0-1.5（不宜过大，否则遮挡游戏元素）
+- **典型错误**：scale 设太大导致爆炸遮挡相邻元素；冰系场景忘记 tint 蓝色
+
+### sparkle — 闪光迸发
+
+- **动画感**：多点闪光粒子从中心向外迸发，6 帧，轻盈感强
+- **最佳用途**：得分反馈；道具拾取；星星闪烁；金币落地
+- **Tint 建议**：金黄（默认得分）；白色（魔法）；粉色（爱心类游戏）
+- **Scale 建议**：0.8-1.2
+- **典型错误**：与 coin_collect 混淆——sparkle 更通用，coin_collect 专为货币设计
+
+### confetti — 彩色纸雨
+
+- **动画感**：多色纸片从上方飘落，12 帧，庆祝感最强
+- **最佳用途**：关卡完成；解锁成就；首次胜利
+- **Tint 建议**：不建议 tint（彩色是其核心特征）
+- **Scale 建议**：1.5-2.0（大范围覆盖效果更好）
+- **典型错误**：对 confetti 使用 tint 导致失去多彩感；scale 太小失去庆祝氛围
+
+### starburst — 星形放射
+
+- **动画感**：多条射线从中心向四周放射，8 帧，视觉冲击强
+- **最佳用途**：大奖励显示；连击触发；技能激活；关键道具出现
+- **Tint 建议**：金色（奖励）；蓝色（技能）；紫色（稀有物品）
+- **Scale 建议**：1.0-2.0
+- **典型错误**：同时使用 starburst + explosion_small 导致视觉混乱
+
+### smoke — 烟雾消散
+
+- **动画感**：烟雾团从中心扩散渐渐透明，8 帧，柔和感
+- **最佳用途**：元素消失动画；角色冲刺残影；爆炸后尘烟
+- **Tint 建议**：白/浅灰（轻盈）；黑/深灰（爆炸尘埃）；浅蓝（冰系）
+- **Scale 建议**：1.0-1.8
+- **典型错误**：浅色背景上用白色 smoke 导致不可见
+
+### glow — 光晕脉冲
+
+- **动画感**：光环从小变大再消散，6 帧，循环感强（可用于持续状态）
+- **最佳用途**：选中状态持续高亮；增益道具激活；关键元素引导注意力
+- **Tint 建议**：与元素主色一致（如选中蓝色元素 -> 蓝色 glow）
+- **Scale 建议**：1.0-1.5（需与元素大小匹配）
+- **典型错误**：glow 颜色与元素颜色不匹配导致视觉割裂
+
+### impact_ring — 撞击扩散环
+
+- **动画感**：圆环从小快速向外扩散，6 帧，物理感强
+- **最佳用途**：物体落地冲击；玩家点击反馈；受击瞬间
+- **Tint 建议**：白色（轻）；橙色（重击）；红色（伤害）
+- **Scale 建议**：1.0-2.0（落地冲击可用较大 scale）
+- **典型错误**：用于持续性效果——impact_ring 是瞬时的，持续高亮应用 glow
+
+### coin_collect — 金币拾取闪光
+
+- **动画感**：金色闪光发散再消失，8 帧，专为金币/货币设计
+- **最佳用途**：金币/宝石/星星拾取；积分获得
+- **Tint 建议**：金黄（默认）；青色（蓝宝石类）；粉色（粉色主题游戏）
+- **Scale 建议**：0.8-1.2（与金币元素大小匹配）
+- **典型错误**：非货币场景误用 coin_collect——通用收集反馈应用 sparkle
+
+---
+
+## 2. Animate 预设完整详解（8 种 + flip）
+
+| 预设名   | 帧数默认 | 动画感                        | 适用素材                   |
+| -------- | -------- | ----------------------------- | -------------------------- |
+| `bounce` | 8        | 竖直正弦平移，上下弹跳        | 角色、可收集道具、悬浮物品 |
+| `float`  | 8        | 上下轻柔漂浮 + 轻微旋转       | 道具、宝箱、魔法效果       |
+| `pulse`  | 8        | 缩放振荡，放大缩小循环        | 按钮、高亮元素、增益图标   |
+| `spin`   | 8        | X 轴缩放振荡模拟 Y 轴旋转     | 金币、奖章、圆形道具       |
+| `shake`  | 8        | 随机小幅 XY 偏移              | 受击反馈、警告、注意力引导 |
+| `blink`  | 8        | 不透明度振荡，显隐循环        | 光标、提示符、倒计时警告   |
+| `swing`  | 8        | 绕顶部中心摆动（钟摆）        | 悬挂物体、灯笼、吊饰       |
+| `wobble` | 8        | 左右交替小幅旋转              | 果冻感物体、软体角色、气泡 |
+| `flip`   | —        | 双面翻转（需正面+背面两张图） | 卡牌翻转、麻将牌、双面道具 |
+
+### bounce — 弹跳
+
+- **动画感**：元素沿 Y 轴做正弦曲线上下移动，最自然的"活着"感
+- **最佳用途**：主角色等待动画；可收集道具提示玩家注意；悬浮的星星/金币
+- **参数建议**：`--frames 8`（流畅）；`--columns 4`
+- **典型错误**：对需要"轻柔飘逸感"的魔法元素用 bounce——应该用 float
+
+### float — 轻柔漂浮
+
+- **动画感**：比 bounce 更轻柔，幅度更小，加入轻微旋转（约 +-3 度），有"飘在空中"的感觉
+- **最佳用途**：魔法道具；宝箱；云朵；任何需要"神秘漂浮感"的元素
+- **参数建议**：`--frames 8-12`；`--columns 4`
+- **典型错误**：对需要明显运动感的可收集道具用 float——幅度太小玩家可能注意不到
+
+### pulse — 缩放振荡
+
+- **动画感**：元素周期性放大（约 120%）再缩回，引导视觉注意力最有效
+- **最佳用途**：CTA 按钮引导点击；教程高亮元素；增益道具图标
+- **参数建议**：`--frames 6`（快速）或 `--frames 12`（缓慢呼吸感）
+- **典型错误**：对游戏主体元素用 pulse——持续缩放让玩家头晕，pulse 只用于 UI 引导
+
+### spin — 旋转
+
+- **动画感**：通过 X 轴缩放模拟 Y 轴旋转，类似金币翻转的平面动画
+- **最佳用途**：金币、奖章、圆形徽章；任何圆形/对称元素
+- **参数建议**：`--frames 8`；注意：此预设不是真 3D 旋转，而是 2D 压缩模拟
+- **典型错误**：对非对称/非圆形元素用 spin——会暴露 2D 压缩的破绽
+
+### shake — 颤抖
+
+- **动画感**：随机小幅位移，制造紧张/警告感
+- **最佳用途**：受击反馈；错误操作提示；血量危险警告；注意力强制引导
+- **参数建议**：`--frames 8-12`（更多帧 = 抖动时间更长）
+- **典型错误**：用 shake 做 idle 动画——持续颤抖让玩家焦虑，idle 应用 bounce/float
+
+### blink — 闪烁
+
+- **动画感**：元素交替显示/隐藏，最简单的"请注意我"动画
+- **最佳用途**：教程光标；限时提示符；倒计时最后几秒；"还有一步"引导
+- **参数建议**：`--frames 4-6`（闪烁频率适中）
+- **典型错误**：blink 帧数太多(>8)导致闪烁太慢、失去紧迫感
+
+### swing — 摆动
+
+- **动画感**：以元素顶部中心为轴心，像钟摆一样左右摆动
+- **最佳用途**：悬挂的灯笼、指示牌、吊饰；任何"挂着"的元素
+- **参数建议**：`--frames 12-16`（较多帧让摆动更平滑）
+- **典型错误**：对地面物体用 swing——违反物理直觉，地面物体应用 wobble
+
+### wobble — 抖动（果冻感）
+
+- **动画感**：左右交替轻微旋转（约 +-5-10 度），有弹性感
+- **最佳用途**：果冻、泡泡、软体角色、气球；任何"软弹弹"的可爱元素
+- **参数建议**：`--frames 8-12`；`--columns 4`
+- **典型错误**：对刚性物体（金属、石头）用 wobble——弹性感与材质矛盾
+
+### flip — 双面翻转
+
+- **动画感**：正面 -> 过渡 -> 背面的完整翻转动画，需要两张图
+- **最佳用途**：卡牌翻转；麻将牌正反面；双面道具；谜题揭示
+- **特殊要求**：必须同时提供 `--input`（正面图）和 `--back`（背面图）
+- **参数建议**：详见 `ta-3d-flip-recipe.md`
+- **典型错误**：忘记提供 --back 参数；正反面尺寸不一致
+
+**flip CLI 示例**：
+
+```bash
+playcraft image animate \
+  --input assets/images/cards/card_front.png \
+  --back assets/images/cards/card_back.png \
+  --preset flip \
+  --output assets/images/cards/card_flip.png
+```
+
+---
+
+## 3. 游戏类型组合配方
+
+### Match-3 消除游戏套餐
+
+| 元素               | 推荐 VFX                 | 推荐 animate | 备注             |
+| ------------------ | ------------------------ | ------------ | ---------------- |
+| 消除爆炸           | `explosion_small`        | —            | tint 按元素颜色  |
+| 得分反馈           | `sparkle`                | —            | 每次消除后触发   |
+| 关卡完成           | `confetti` + `starburst` | —            | 双 VFX 叠加      |
+| 可移动元素（等待） | —                        | `bounce`     | 待操作的关键元素 |
+| 特殊道具           | `glow`                   | `pulse`      | 高亮 + 引导点击  |
+| 连击               | `starburst`              | —            | 大 scale=1.5     |
+
+```bash
+# Match-3 标准消除特效
+playcraft image use-vfx --preset explosion_small --tint "#FF6B35" --output assets/images/vfx/tile_break.png
+playcraft image use-vfx --preset sparkle --output assets/images/vfx/score_sparkle.png
+playcraft image animate --input assets/images/tiles/special_bomb.png --preset pulse --frames 8 --output assets/images/tiles/special_bomb_anim.png
+```
+
+### 跑酷 / 平台跳跃套餐
+
+| 元素           | 推荐 VFX                   | 推荐 animate | 备注          |
+| -------------- | -------------------------- | ------------ | ------------- |
+| 道具收集       | `coin_collect` / `sparkle` | —            | 根据道具类型  |
+| 冲刺残影       | `smoke`                    | —            | tint 深灰或黑 |
+| 落地冲击       | `impact_ring`              | —            | scale=1.5     |
+| 跑动中角色等待 | —                          | `bounce`     | 开始前的角色  |
+| CTA 按钮       | —                          | `pulse`      | 引导安装      |
+| 金币           | —                          | `spin`       | 圆形金币旋转  |
+
+```bash
+playcraft image use-vfx --preset smoke --tint "#666666" --output assets/images/vfx/dash_smoke.png
+playcraft image use-vfx --preset impact_ring --scale 1.5 --output assets/images/vfx/land_impact.png
+playcraft image animate --input assets/images/ui/coins.png --preset spin --frames 8 --output assets/images/ui/coins_spin.png
+```
+
+### 卡牌 / 麻将套餐
+
+| 元素         | 推荐 VFX                 | 推荐 animate | 备注                    |
+| ------------ | ------------------------ | ------------ | ----------------------- |
+| 卡牌翻转     | —                        | `flip`       | 见 ta-3d-flip-recipe.md |
+| 胜利展示     | `confetti` + `starburst` | —            | —                       |
+| 选中卡牌     | `glow`                   | —            | tint 与牌背色匹配       |
+| 特殊牌效果   | `sparkle`                | —            | —                       |
+| 等待中的牌组 | —                        | `wobble`     | 轻柔抖动                |
+
+```bash
+playcraft image use-vfx --preset glow --tint "#FFD700" --output assets/images/vfx/card_select_glow.png
+playcraft image animate --input assets/images/cards/hand_pile.png --preset wobble --frames 8 --output assets/images/cards/hand_pile_wobble.png
+```
+
+### 休闲益智 / 泡泡射击套餐
+
+| 元素       | 推荐 VFX                      | 推荐 animate | 备注         |
+| ---------- | ----------------------------- | ------------ | ------------ |
+| 泡泡消除   | `explosion_small` + `sparkle` | —            | 双 VFX       |
+| 浮动的泡泡 | —                             | `float`      | 轻柔感       |
+| 瞄准指示   | —                             | `blink`      | 提示玩家操作 |
+| 星星收集   | `coin_collect`                | `spin`       | —            |
+| 过关庆祝   | `confetti`                    | —            | —            |
+
+---
+
+## 4. 自定义动画帧数决策指南
+
+> 本节适用于不使用 animate 内置预设的场景——从独立帧手动合成精灵图（`playcraft image sprite-sheet`），或 AI 批量生成序列帧（`playcraft-sprite-generation` Skill）时。
+
+### 4.1 各动画类型的帧数基准
+
+| 动画类型      | 建议帧数 | 建议 FPS       | 关键注意点                                               |
+| ------------- | -------- | -------------- | -------------------------------------------------------- |
+| Idle（待机）  | 2-4 帧   | 6-8 FPS        | 极简为主；2 帧（呼吸缩放）足以表达"活着"                 |
+| Walk（行走）  | 4-8 帧   | 8-12 FPS       | 32x32 以下用 4 帧；64x64 以上用 6-8 帧                   |
+| Run（奔跑）   | 6-8 帧   | 10-12 FPS      | 用更高 FPS 而非更多帧；8 帧 @12FPS 比 16 帧 @6FPS 更流畅 |
+| Jump（跳跃）  | 3-5 帧   | 可变           | 上升 1 帧 + 顶点 1 帧 + 下降 1 帧已足够                  |
+| 攻击/打击     | 3-6 帧   | 可变（见 4.2） | 帧时长分配才是关键                                       |
+| 消除/爆炸特效 | 4-8 帧   | 12-15 FPS      | 多于 8 帧视觉改善边际递减                                |
+| UI 元素动画   | 2-4 帧   | —              | 强烈建议用 CSS animation 替代（0KB 开销）                |
+| 卡牌/翻转     | 16 帧    | 24 FPS         | 用 `playcraft-3d-flip-sprite` Skill                      |
+
+**体积估算公式**：
+
+```
+精灵图体积 = 每帧宽 x 每帧高 x 帧数 x 4 bytes (RGBA) x 0.3 (PNG 压缩率)
+示例：128x128 x 8帧 = 512KB 原始 -> ~50KB PNG
+```
+
+### 4.2 非均匀帧时长（比增加帧数更有效）
+
+可玩广告 5MB 预算紧张，不要用增加帧数追求流畅感——用非均匀帧时长创造冲击力，效果更好且不增加体积。
+
+```
+攻击动画（5 帧）的帧时长分配示例：
+  帧 1（蓄力开始）: 80ms   <- 快速进入
+  帧 2（蓄力末）:   80ms
+  帧 3（打击瞬间）: 40ms   <- 最短，创造冲击感
+  帧 4（打击后）:   180ms  <- hold 住打击帧，让玩家"看见"命中
+  帧 5（恢复）:     120ms
+
+共 5 帧 500ms，比均匀的 5 帧 @10FPS 感知效果强 3-5 倍
+```
+
+在代码层实现非均匀帧时长（Developer 负责，TA 需在 ta-log 中注明建议）：
+
+```javascript
+// 告诉 Developer 的帧时长数组（写入 ta-log.md）
+// const ATTACK_FRAME_DURATIONS = [80, 80, 40, 180, 120]; // ms per frame
+```
+
+### 4.3 何时用精灵图，何时改用其他方案
+
+```
+需要动画效果？
+|
++-- 简单变换（位移/缩放/透明度/旋转）？
+|   -> CSS animation / CSS transition（Developer 实现，0KB 开销，GPU 合成）
+|
++-- 矢量图标动画（CTA 脉冲/教程手势）？
+|   -> Lottie JSON（~30KB，矢量，跨分辨率）
+|
++-- VFX 特效（爆炸/闪光/纸雨）？
+|   -> playcraft image use-vfx（内置预设，最快最省）
+|
++-- 内置预设（bounce/spin/pulse 等）满足需求？
+|   -> playcraft image animate --preset <name>
+|
++-- 3D 翻转（卡牌/麻将/双面道具）？
+|   -> playcraft-3d-flip-sprite Skill（16 帧软光栅渲染）
+|
++-- 以上都不满足（复杂序列帧、角色行走/攻击）？
+    -> 精灵图（AI 批量生成帧 -> sprite-sheet 合并）
+       参考：playcraft-sprite-generation Skill
+```
+
+---
+
+## 5. VFX 体积预算参考
+
+| 游戏复杂度         | 建议 VFX 总体积上限 | 配置策略                      |
+| ------------------ | ------------------- | ----------------------------- |
+| 简单（1-2 种 VFX） | <= 60KB             | `sparkle` + `coin_collect`    |
+| 中等（3-4 种）     | <= 100KB            | 加 `explosion_small` + `glow` |
+| 丰富（5+ 种）      | <= 150KB            | 全套，注意总文件大小预算      |
+
+> TA 在选择 VFX 组合时，需结合 layout-spec.md 中的总体积预算（通常 <= 2-3MB 给所有素材）。VFX 精灵图应优先使用小体积预设，大型 VFX（confetti 25KB）控制在 1-2 个。
+
+### 5MB 预算中的动画体积分配建议
+
+| 资产类别           | 建议体积上限 | 备注                        |
+| ------------------ | ------------ | --------------------------- |
+| 核心游戏元素精灵图 | 1.5-2 MB     | 包含所有 tile/角色/道具     |
+| VFX 精灵图         | <= 150 KB    | 用内置预设控制              |
+| UI 动画（Lottie）  | <= 100 KB    | CTA 脉冲、教程手势          |
+| 背景/场景图        | <= 500 KB    | WebP 格式优先               |
+| 音频               | <= 300 KB    | BGM + 关键 SFX              |
+| 代码 + 框架        | <= 800 KB    | 按引擎 playcraft build 优化 |
+
+> Base64 编码注意：单 HTML 格式（IronSource / AppLovin / Snapchat）所有资源 Base64 内联后体积增加 ~33%。即 5MB 限制的单 HTML，实际可用原始资产 <= 3.75MB。Google Ads ZIP 格式无此限制，5MB 全部可用。
+
+---
+
+## 6. CLI 参数完整速查
+
+### playcraft image use-vfx 完整参数
+
+| 参数       | 类型       | 默认值               | 说明                     |
+| ---------- | ---------- | -------------------- | ------------------------ |
+| `--preset` | string     | 必填                 | VFX 预设名               |
+| `--output` | string     | 必填                 | 输出精灵表路径（.png）   |
+| `--tint`   | hex string | 无（使用预设默认色） | 颜色叠加，格式 `#RRGGBB` |
+| `--scale`  | number     | `1.0`                | 整体缩放倍数（0.5-3.0）  |
+
+### playcraft image animate 完整参数
+
+| 参数             | 类型   | 默认值   | 说明                                |
+| ---------------- | ------ | -------- | ----------------------------------- |
+| `--input`        | string | 必填     | 输入图片路径（素材原图）            |
+| `--output`       | string | 必填     | 输出精灵表路径（.png）              |
+| `--preset`       | string | `bounce` | 动画预设名                          |
+| `--frames`       | number | `8`      | 总帧数，范围 2-64                   |
+| `--columns`      | number | `4`      | 精灵表列数（行数 = frames/columns） |
+| `--back`         | string | 无       | flip 专用：背面图片路径             |
+| `--list-presets` | flag   | —        | 打印所有预设说明后退出              |
+
+### playcraft image list-vfx 参数
+
+| 参数     | 说明                                           |
+| -------- | ---------------------------------------------- |
+| `--json` | 以 JSON 格式输出预设列表（含帧数、体积等字段） |

package/project-template/.claude/agents/reviewer.md

@@ -0,0 +1,127 @@
+---
+description: "Reviewer: design_check (Gate pre-check) + ui_diff (MC screenshots) + load_check (no errors) — playwright-cli; no build."
+allowedTools:
+  - "Read"
+  - "Write"
+  - "Grep"
+  - "Glob"
+  - "Skill"
+  - "Bash(ls:*)"
+  - "Bash(cat:*)"
+  - "Bash(find:*)"
+  - "Bash(du:*)"
+  - "Bash(wc:*)"
+  - "Bash(grep:*)"
+  - "Bash(npm run dev*)"
+  - "Bash(playcraft image info:*)"
+  - "Bash(playcraft audio info:*)"
+  - "Bash(playwright-cli:*)"
+  - "Bash(npx playwright-cli:*)"
+---
+
+> **First Step**: Read `docs/project-state.md` → **`## Agent handoff`** → **## Runtime** → branch; read `refs/` only when Runtime says so. STOP: [STOP sync checklist](../../docs/team/collaboration.md#stop-sync-checklist).
+
+# Reviewer — Playable Ads Convergence Review Agent
+
+## Agent Conduct
+
+> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; audit-only; orchestrator owns all `stage` transitions.
+
+## Runtime (on invoke)
+
+1. Read `docs/project-state.md` → parse `## Agent handoff` YAML + orchestrator-specified **review mode**.
+2. If `subagent_stop: true` and `subagent: reviewer` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**.
+3. Branch (mode from orchestrator invoke message or `next_orchestrator_action`):
+
+| Mode               | Preconditions                       | This round                                                             | On STOP (pass)                                                                                      | On STOP (fail)                                                                                                  |
+| ------------------ | ----------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **`design_check`** | Gate #1 or #2b materials ready      | Soft checklist on docs / MC / ASR — **no subjective quality judgment** | `next_orchestrator_action: "Run Gate #1"` or `"Run Gate #2b"`                                       | Route to PM/Designer with missing items; `next_orchestrator_action: "Re-invoke @pm"` or `"Re-invoke @designer"` |
+| **`ui_diff`**      | `devStatus: ui_ready`, devUrl valid | **`playwright-cli`** screenshots vs MC panels; UI Diff Report          | `uiReviewStatus: passed` → `next_orchestrator_action: "Set stage=gameplay_pass, invoke @developer"` | `uiReworkRound` +1 → `next_orchestrator_action: "Set stage=ui_rework, invoke routed agents per review-report"`  |
+| **`load_check`**   | `devStatus: ready`, devUrl valid    | **`playwright-cli`** open devUrl + console — no gameplay walkthrough   | `loadCheck: passed` → `next_orchestrator_action: "Run Gate #3 with devUrl"`                         | Route Developer → `next_orchestrator_action: "Re-invoke @developer for load_check fixes"`                       |
+
+4. Append `--- PLAYCRAFT_STOP ---` (`role: reviewer`).
+
+**UI rework limit:** max **5** `uiReworkRound`. At round 5 with fail → note in report; handoff `Set stage=gameplay_pass` or escalate per orchestrator policy.
+
+## Mission
+
+> Team mission: see [CLAUDE.md](../../CLAUDE.md#mission). Stage 链路与上下游: [CLAUDE.md § Stage Model](../../CLAUDE.md#stage-model).
+
+## Goals
+
+**Three convergence modes (orchestrator picks one per invoke):**
+
+| Mode             | Weight  | Pass condition                                     |
+| ---------------- | ------- | -------------------------------------------------- |
+| **design_check** | Light   | Soft checklist all pass (obvious defects only)     |
+| **ui_diff**      | Heavy   | Screenshots vs MC — no critical/major visual diffs |
+| **load_check**   | Minimal | Page loads ≤10s; console has no Error-level logs   |
+
+**Non-goals:** production fixes; subjective design critique in `design_check`; AI gameplay walkthrough; six-dimension scoring.
+
+You are an **independent QA** — audit lens only; **no production participation**.
+
+---
+
+## Core Skills
+
+Reviewer 浏览器验证依赖 **`playwright-cli`**。**`ui_diff` / `load_check` 前必须先读 Skill：**
+
+| Skill                | Path                                                                          | When                    |
+| -------------------- | ----------------------------------------------------------------------------- | ----------------------- |
+| **`playwright-cli`** | [`.claude/skills/playwright-cli/SKILL.md`](../skills/playwright-cli/SKILL.md) | `ui_diff`, `load_check` |
+
+**典型流程（9:16 手机视口）：**
+
+```bash
+playwright-cli open <devUrl>
+playwright-cli resize 390 844
+playwright-cli screenshot --filename=logs/review-<scene>.png
+playwright-cli console
+playwright-cli close
+```
+
+`design_check` 不需要浏览器。MC 比例验证用 `playcraft image info`。
+
+---
+
+## Review flow (summary)
+
+**Primary L2:** [`refs/reviewer-convergence-eval.md`](refs/reviewer-convergence-eval.md) — checklists + `ui_diff` / `load_check` procedures.
+
+| Mode             | Steps                                                              |
+| ---------------- | ------------------------------------------------------------------ |
+| **design_check** | Gate #1 or #2b checklist → pass/fail + routeTo                     |
+| **ui_diff**      | MC paths → devUrl screenshots per scene → compare → UI Diff Report |
+| **load_check**   | devUrl load + console → one screenshot → pass/fail                 |
+
+---
+
+## File Access
+
+**Read:** `docs/project-state.md`, `design-brief.md`, `layout-spec.md`, `atom-plan.json`, `atom-plan.md`, `style-exploration.md`, `logs/designer-log.md`, `logs/ta-log.md`, `logs/developer-log.md`, `assets/images/reference/`, `game/` (code audit only).
+
+**Write:** `logs/review-report.md`; `docs/project-state.md` (checkpoint: `uiReviewStatus`, `uiReworkRound`, `loadCheck`, handoff only).
+
+## Tools
+
+**Browser (core):** **`playwright-cli`** — `open` / `resize` / `screenshot` / `console` / `close`. See [Core Skills](#core-skills).
+
+**Dev server:** `npm run dev` if devUrl unreachable.
+
+**Asset audit:** `playcraft image info` (MC ratio check in `design_check`).
+
+## Output
+
+Use `templates/review-report.template.md` — fill the section matching review mode (`design_check` / `ui_diff` / `load_check`).
+
+Afterward update handoff per **Runtime**. **Never** write mainline `stage`.
+
+## Important Rules
+
+1. **Never modify production files** — only `logs/review-report.md` and `docs/project-state.md` checkpoint.
+2. **`design_check` is soft** — block missing docs / wrong MC ratio / empty assetMapping; do not fail for aesthetics.
+3. **`ui_diff` uses playwright-cli** — save screenshots under `logs/`; each diff needs severity + `routeTo: developer | ta | designer`.
+4. **`load_check` is not gameplay QA** — only load + console errors; gameplay = user at Gate #3.
+5. **`uiReworkRound` max 5** — increment on `ui_diff` fail; minor issues log only, do not block pass.
+6. **Orchestrator owns stage** — you set handoff `next_orchestrator_action` only.