@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/skills/playable-art/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: playable-art
+description: >-
+  GPT-image-2 art import for playables (steps ①②). Agent MUST run ensure-project,
+  write/read design constraints, import v2 pipeline, build-atlas, review processed
+  assets visually, verify:ui:assets.
+  Use when user asks to replace placeholder tiles/UI with generated art.
+  User never runs import scripts manually.
+---
+
+# Playable GPT Art Pipeline
+
+> **用户**：「用 gpt art pipeline 替换当前占位美术 / 生成 tile atlas」  
+> **Agent**：ensure-project → 读约束 → import → build-atlas → review:assets → verify。
+
+---
+
+## Agent 入口
+
+### 0. 自举
+
+```bash
+npm run ensure:project
+```
+
+确认/编写约束：`docs/vds.md`、`playable.ui.profile.yaml` assets 段、或 skill 内 `references/`。
+
+### 1. 读 art contract
+
+扫描 `assets/manifest.json`、atlas JSON、现有 frame 名 — **不改名**。
+
+### 2. 导入链（Agent 执行）
+
+```bash
+# ensure-project 已合并 package.json 时可：
+npm run mark:slices     # 可选预检：只生成 slice-plan 和标注图，不写最终切图
+npm run import:gpt-art    # 若无则 node ../skills/.../import-gpt-art-sheets-v2.py
+npm run build-atlas
+npm run review:assets     # 必做：生成处理后图片/视频 contact sheet，agent 必须查看
+npm run verify:ui:assets
+```
+
+需 API 时读环境 `WAVESPEED_API_KEY`；无 key 则 chroma 本地 fallback（见 references）。
+透明资产必须先选 `alphaStrategy`（见 [references/alpha-postprocess.md](references/alpha-postprocess.md)），并保留 raw 输入到 `assets/reference/raw/`。
+
+### 3. Image Gate
+
+```bash
+npm run verify:ui
+```
+
+PASS 后交 video-validate-loop 录屏定案（静态 PASS ≠ 合成 PASS）。
+
+### 4. 硬边 UI / soft glow FX 分工
+
+- 本 skill：tile、HUD、CTA atlas（#ff00ff contain）
+- 帧动画 ADD 光效 → `playable-fx-peak`（出图 prompt + repack 见该 skill § GPT 出图与 A/B）
+
+### 5. Alpha Postprocess Strategy
+
+AI 生图通常没有可信透明底。每个需要透明的 UI / sprite / VFX（Visual Effects, 视觉特效）资产必须在生成前选择一种 `alphaStrategy`：
+
+| alphaStrategy     | 用途                                                   | 后处理                                                                                | 何时切换                                       |
+| ----------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `chroma`          | 硬边 UI（User Interface, 用户界面）、文字、普通 sprite | 绿/蓝/品红纯色底 → floodfill / chroma key → RGBA (Red Green Blue Alpha, 红绿蓝透明度) | 有色边残留 → 换 key 色或转 `rgb-alpha-split`   |
+| `dual-bg-diff`    | 半透明边缘、抗锯齿、轻柔阴影                           | 两张同构图不同底色 → 差分 matte → residual gate                                       | 几何漂移 / 双主体 → 重生或转 `rgb-alpha-split` |
+| `rgb-alpha-split` | 稳定透明 sprite、UI、VFX                               | 左半 RGB (Red Green Blue, 红绿蓝)，右半 Alpha 灰度 → 合成 RGBA                        | 模型无法画准灰度 matte 时退回 `chroma`         |
+| `black-add`       | glow、粒子、光环、光柱                                 | 黑底保留，运行时 ADD blend                                                            | 需要 NORMAL blend 时转 `rgb-alpha-split`       |
+
+脚本入口：
+
+```bash
+python3 skills/playable-art/scripts/extract-alpha-split.py <split.png> <out.png>
+python3 skills/playable-art/scripts/extract-dual-bg-alpha.py <green.png> <blue.png> <out.png> --bg-a 00ff00 --bg-b 0000ff
+python3 skills/playable-art/scripts/verify-alpha-clean.py <out.png> --json
+```
+
+---
+
+## Reference Matching（对照参考图）
+
+> 原 `playable-ui-reference-matching` 已并入。
+
+1. 截当前实现 + 读 `reference/` 参考图
+2. 按层级对比：HUD → board → CTA → combo/reward → 背景景深
+3. 判断差距类型：layout / 素材质量 / 比例 / 层级 / 色 / 交互态
+4. **先改高影响区**，再微调；不要孤立调单个元素
+5. 1080×1920 视口浏览器截图验收
+
+规则：大区域用 design canvas 比例；preserve aspect ratio；CTA/HUD/board 为构图锚点。
+
+详见 [references/reference-comparison.md](references/reference-comparison.md)、[references/layout-proportions.md](references/layout-proportions.md)。
+
+## Workflow
+
+1. Inspect the project art contract: atlas frame names, source PNG paths, target dimensions, build script, and verification command.
+2. Generate GPT-image-2 sheets using the selected `alphaStrategy`; default to `chroma` only for hard-edge assets.
+3. Save original sheets under `assets/reference/raw/` before any background removal or slicing.
+4. Import with **v2 pipeline** (recommended):
+
+```bash
+export WAVESPEED_API_KEY=...   # optional; chroma fallback if unset
+npm run import:gpt-art         # scripts/import-gpt-art-sheets-v2.py
+npm run build-atlas
+npm run review:assets
+npm run verify:ui:assets
+```
+
+V2 steps: **remove bg / alpha extraction → mark slices → segment elements (not grid cells) → contain-scale → center**. See [references/sheet-import-v2.md](references/sheet-import-v2.md) and [references/alpha-postprocess.md](references/alpha-postprocess.md).
+
+5. Inspect `assets/reference/marked/*-slice-marks.png`, `assets/reference/slice-plan.json`, `assets/atlas/*.png`, and `validate/art-review/processed-images-contact-sheet.png` for clipping, residue, wrong orientation, and distorted text.
+6. Run `npm run verify:ui` before finishing.
+
+**Do not use legacy grid inset importer** for wide plaques/toasts — it clips left/right ornaments.
+
+## Generation Rules
+
+- Ask GPT-image-2 for sprite sheets, not individual scattered art, when assets share style and dimensions.
+- Use exact grid language: `strict 4 columns x 3 rows`, `exactly N centered sprites`, `unused cells empty`.
+- For `chroma`, require `perfectly flat #ff00ff background`, `no dividers`, `no watermark`, `no shadows outside each sprite cell`.
+- For `dual-bg-diff`, generate two geometry-identical images with different flat backgrounds; if geometry cannot be held stable, use `rgb-alpha-split`.
+- For `rgb-alpha-split`, require a left RGB image and right grayscale Alpha matte; white means opaque and black means transparent.
+- For `black-add`, require pure black `#000000`, generous spacing, and no cropped glow.
+- Require generous padding. For wide plaques/toasts, prefer fewer columns or single-image overrides so text is not clipped at cell edges.
+- For text-bearing UI, say `preserve aspect ratio, not stretched, not clipped`.
+- Keep Chinese text short and explicit. Check generated text manually; regenerate bad text instead of trying to repair it by scaling.
+- For directional/tutorial assets, specify orientation and anchor intent, e.g. `finger points downward; fingertip at bottom`.
+
+See `references/prompt-patterns.md` for compact prompts.
+
+## Import Rules
+
+- Mark First, Slice Second: v2 importer must generate `assets/reference/slice-plan.json` and `assets/reference/marked/*-slice-marks.png` before writing `assets/images/**`. These programmatic marks make clipping visible to VLM (Vision-Language Model, 视觉语言模型) review and give the slicer deterministic `safeSliceBox` coordinates.
+- Use `npm run mark:slices` when you want to inspect the marks before importing. It must not overwrite final sliced assets.
+- Review After Processing: after any image or video transform, run `npm run review:assets` and inspect the generated contact sheet before using the result in game code. Passing scripts is not acceptance; visual review evidence is acceptance.
+- Always keep source art aspect ratio. Use **contain**: scale uniformly to fit inside the fixed target rectangle, then center on transparent canvas.
+- Do not use cover or stretch for UI plaques, toasts, buttons, or digits; it will distort text and decorative borders.
+- Use chroma-key removal for `#ff00ff`, then crop to alpha.
+- Use `extract-alpha-split.py` for `rgb-alpha-split`; reject non-even source widths or non-grayscale-looking alpha halves.
+- Use `extract-dual-bg-alpha.py` for `dual-bg-diff`; reject geometry residual failures and regenerate or switch strategy.
+- Use `black-add` for additive glow VFX that lose halo during background removal; verify with `playable-fx-peak` clean harness.
+- Remove small disconnected components to eliminate grid fragments, key-color fringe, and random GPT leftovers.
+- Use `icon` mode for single-subject art such as hand icons, gifts, particles, shards, and glows; keep only the largest connected component.
+- Use `digit` mode for number sheets: crop from strong alpha/core first, then contain-fit so `1` does not appear tiny or all digits drift in size.
+- Use overrides for bad cells instead of repeatedly accepting a flawed sheet. Store single regenerated assets under `assets/reference/` and import them over the sheet-derived frame.
+
+## Scripts
+
+This skill includes scripts that are meant to be copied into a target playable project:
+
+- `scripts/import-gpt-art-sheets.py`: configurable importer for UI, rewards, digits, glow digits, and fx sheets.
+- `scripts/import-gpt-art-sheets-v2.py --mark-only`: programmatic slice marking. It emits `slice-plan.json` and marked reference sheets without writing final sprites.
+- `scripts/review-processed-assets.py`: creates `validate/art-review/processed-images-contact-sheet.png`, optional video thumbnails, and `processed-assets-review.json` after asset processing.
+- `scripts/import-gpt-tile-sheet.py`: importer for Mahjong tile sheets.
+- `scripts/extract-alpha-split.py`: converts side-by-side RGB + Alpha matte art into RGBA.
+- `scripts/extract-dual-bg-alpha.py`: extracts RGBA from two geometry-matched flat-background renders.
+- `scripts/verify-alpha-clean.py`: fails missing alpha, fully opaque outputs, and common chroma/white/black edge residue.
+
+After copying, update:
+
+- `SPECS`: sheet filename, grid size, frame names, output paths, target dimensions.
+- `OVERRIDES`: single-frame replacements for clipped text, wrong orientation, or bad cells.
+- Any project-specific paths if the project does not use `assets/reference` and `assets/images`.
+
+Run:
+
+```bash
+python3 scripts/import-gpt-art-sheets.py
+npm run mark:slices
+python3 scripts/import-gpt-tile-sheet.py
+npm run build-atlas
+npm run review:assets
+npm run verify:ui
+```
+
+If the project has no verification script, at least run the atlas build, inspect atlas PNGs, and load the game in a browser.
+
+## Common Fixes
+
+- **CTA end caps look oval / button too wide:** regenerate with ~2.3:1 aspect, no baked text; see [references/cta-art-spec.md](references/cta-art-spec.md).
+- **Text is stretched:** remove stretch/cover logic; use contain only; regenerate if the source text is already warped.
+- **Sprite is clipped:** regenerate that sheet with more padding or create a single-image override.
+- **Grid line appears in atlas:** increase cell inset and connected-component filtering.
+- **Green / blue / magenta fringe:** switch chroma color or regenerate as `rgb-alpha-split`.
+- **White antialias edge:** use `dual-bg-diff` or `rgb-alpha-split`; then run `verify-alpha-clean.py`.
+- **Dual-bg double subject:** geometry drift; regenerate with a fixed reference or switch to `rgb-alpha-split`.
+- **Glow halo clipped:** use `black-add` and route through `playable-fx-peak`.
+- **Small icon has random fragments:** use icon mode and keep largest component only.
+- **Digit `1` is too small:** crop from strong alpha/core and contain-fit; do not force nonuniform scaling.
+- **Timer colon shows as `x`:** colon dots split into two blobs during segmentation; ensure `merge_stacked_fragments` + row-band sort run before blob selection. See [references/sheet-import-v2.md](references/sheet-import-v2.md#digit-symbols-colon-shows-as-x).
+- **Hand points the wrong way:** create an orientation-specific override and preserve the game’s expected origin/anchor.
+- **Atlas exceeds budget:** prefer optimized PNG save; for large GPT UI atlases, indexed PNG quantization may be acceptable after visual inspection.
+
+## Final Validation
+
+Before finishing:
+
+- Inspect `assets/atlas/*.png`, not only individual source PNGs.
+- Inspect `validate/art-review/processed-images-contact-sheet.png` after imports, atlas builds, alpha extraction, video conversion, or overrides.
+- Confirm all target frame sizes still match the project manifest/profile.
+- Confirm generated text is readable at in-game display size.
+- Confirm no sprite has visible chroma-key residue, clipped edges, or orientation errors.
+- Run the project verification command and report remaining warnings separately from failures.

package/project-templates/phaser/skills/playable-art/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Playable GPT Art Pipeline'
+  short_description: 'GPT sheet workflow for playable game atlases'
+  default_prompt: 'Use $playable-art to replace low-quality playable game atlas art with GPT-generated sprite sheets.'

package/project-templates/phaser/skills/playable-art/references/alpha-postprocess.md

@@ -0,0 +1,46 @@
+# Alpha Postprocess Strategy
+
+AI image generation usually does not return reliable transparent pixels. Every transparent runtime asset must choose one alpha strategy before bulk generation, then preserve the raw input under `assets/reference/raw/` and produce an RGBA (Red Green Blue Alpha, 红绿蓝透明度) PNG/WebP for runtime use.
+
+## Strategy Matrix
+
+| Strategy | Use for | Generation requirement | Postprocess | Fallback |
+| -------- | ------- | ---------------------- | ----------- | -------- |
+| `chroma` | Hard-edge UI (User Interface, 用户界面), text, regular sprites | Pure green, blue, or magenta background that does not conflict with the subject palette | Flood-fill / chroma key removal, then dark-bg overlay verify | `rgb-alpha-split` when edge residue remains |
+| `dual-bg-diff` | Antialiased edges, soft shadows, semi-transparent objects | Two geometry-identical renders with different flat backgrounds | Difference matte extraction with geometry residual check | Regenerate or switch to `rgb-alpha-split` when geometry drifts |
+| `rgb-alpha-split` | Stable sprites, UI, VFX (Visual Effects, 视觉特效) needing precise transparency | One image split left/right: left is RGB (Red Green Blue, 红绿蓝), right is grayscale Alpha | Copy left RGB, use right luminance as alpha | `chroma` only for hard-edge assets |
+| `black-add` | Glow, rings, particles, beams | Pure black `#000000` background with generous spacing | Keep black-backed sheet and use ADD blend at runtime | `rgb-alpha-split` if NORMAL blend is required |
+
+## Prompt Requirements
+
+- `chroma`: name the exact key color and say `perfectly flat`, `no texture`, `no shadow on background`.
+- `dual-bg-diff`: generate two images with identical composition and different flat backgrounds; if the model cannot keep geometry fixed, do not use this strategy.
+- `rgb-alpha-split`: ask for a single image where the left half is the full-color sprite and the right half is the matching grayscale alpha matte; white means opaque, black means transparent.
+- `black-add`: ask for pure black background, no cropped glow, and enough spacing between frames.
+
+## Script Entrypoints
+
+```bash
+python3 skills/playable-art/scripts/extract-alpha-split.py \
+  assets/reference/raw/ui_alpha_split.png assets/images/ui/button.png
+
+python3 skills/playable-art/scripts/extract-dual-bg-alpha.py \
+  assets/reference/raw/icon_green.png assets/reference/raw/icon_blue.png assets/images/ui/icon.png \
+  --bg-a 00ff00 --bg-b 0000ff
+
+python3 skills/playable-art/scripts/verify-alpha-clean.py assets/images/ui/icon.png --json
+```
+
+## Validator Routing
+
+Image Validator feedback should route failures to production skills:
+
+| Symptom | Recommended route |
+| ------- | ----------------- |
+| Green / blue / magenta fringe | `playable-art`: switch `chroma` color or use `rgb-alpha-split` |
+| White edge or dirty antialiasing | `playable-art`: use `dual-bg-diff` or `rgb-alpha-split` |
+| Dual-bg residual / double subject | `playable-art`: regenerate with fixed reference or switch to `rgb-alpha-split` |
+| Halo clipped after remove-bg | `playable-fx-peak`: use `black-add` and headed clean harness |
+| Crack / damage tied to wrong tile face | `playable-fx-decompose`: rebuild overlay from blank reference |
+
+Video Validator feedback should include `timestamp -> visible symptom -> severity -> recommended skill -> recommended alphaStrategy`. Video alpha is currently a production convention, not a full encoding pipeline; use `chroma-video`, `dual-bg-video`, `rgb-alpha-video`, or `opaque-video` in TA logs to document the chosen method.

package/project-templates/phaser/skills/playable-art/references/cta-art-spec.md

@@ -0,0 +1,59 @@
+# CTA Button Art Spec
+
+避免「图+字」布局阶段反复翻车。出图时按此约束，少靠运行时拉伸补救。
+
+## Target Proportions
+
+| 属性   | 推荐                          | 避免                       |
+| ------ | ----------------------------- | -------------------------- |
+| 宽高比 | **2.0–2.6 : 1**（如 520×200） | >3.5:1 超宽胶囊（820×190） |
+| 文字   | **不 bake 进底图**            | 与「立即下载」合成在图里   |
+| 端饰   | 圆形宝石、祥云耳比例饱满      | 扁椭圆耳                   |
+
+运行时默认 **等比缩放**；超宽素材只能等比缩小，无法「只变窄不变形」。
+
+## 9-Slice Friendly Structure
+
+若必须支持宽度可调：
+
+```
+[左耳 cap 固定 ~120px][中间红条可平铺][右耳 cap 固定 ~120px]
+```
+
+- 左右 cap 含完整祥云/流苏，**不要**与中间红条共用变形区域
+- 中间条纹理可水平无缝重复
+- 上下金边在 cap 内闭合
+
+## Content Safe Zone（导出前标注）
+
+在 PSD / 生成 prompt 中留出：
+
+| 边                     | 约占帧高               |
+| ---------------------- | ---------------------- |
+| top                    | 18–22%                 |
+| bottom                 | 20–24%（下金边常更厚） |
+| left/right（无图标时） | 各 12–15%              |
+
+带左侧图标 HUD 条：左侧 30–35% 留给图标，文字区在右 55%。
+
+## Generation Prompt — CTA Single Frame
+
+```text
+Single Chinese cute mobile game CTA button on perfectly flat #ff00ff background.
+Horizontal pill button, aspect ratio about 2.3:1 (moderately wide, NOT ultra-wide banner).
+Ornate fixed left and right gold cloud end caps with round green gems and red tassels.
+Center is plain red lacquer band for overlay text — do NOT render text on the button.
+Caps must look circular, not stretched ovals. Huge padding inside the red band.
+Fully visible, upright, no clipping, no watermark.
+```
+
+## Import
+
+- **contain** 放入目标矩形，禁止 stretch
+- 若 sheet cell 过宽：单独 override 导出 `ui/cta_btn.png`
+- 导入后：`npm run verify:ui:layout`；必要时设 `CTA_TEXT_Y_RATIO`
+- 图+字 inset 实测：`python3 skills/playable-verify-ui/scripts/measure_frame_content.py assets/atlas/ui.png assets/atlas/ui.json ui_cta_btn`
+
+## Related
+
+- [playable-verify-ui](../playable-verify-ui/SKILL.md) — layout / Frame+Text

package/project-templates/phaser/skills/playable-art/references/layout-proportions.md

@@ -0,0 +1,30 @@
+# Layout Proportions
+
+Use proportions for large playable UI elements.
+
+## Screen Regions
+
+- Top HUD: reserve enough height for readable timer/progress panels.
+- Board: keep the play area central but leave a deliberate lower feedback band.
+- Bottom CTA: make it a real visual anchor, not small text.
+- Combo/reward feedback: give it a dedicated band so it does not overlap the board or CTA.
+
+## Sizing Rules
+
+- Base major dimensions on `DESIGN_WIDTH` and `DESIGN_HEIGHT`.
+- Compute badge height from source aspect ratio when using bitmap art.
+- Keep hit zones at least as large as the visible button.
+- Recalculate dependent positions after increasing sizes.
+
+## Image Aspect
+
+- Check source dimensions before resizing.
+- Use `targetH = targetW / sourceAspect` for fixed-width scaling.
+- Use `targetW = targetH * sourceAspect` for fixed-height scaling.
+- Use contain-style sizing when both max width and max height matter.
+
+## Disabled Or Blocked States
+
+- Avoid alpha-only states for stacked boards.
+- Prefer tint plus solid overlay so hidden content does not show through.
+- Preserve readable symbols on disabled pieces.

package/project-templates/phaser/skills/playable-art/references/prompt-patterns.md

@@ -0,0 +1,83 @@
+# Prompt Patterns
+
+Use these as compact starting points. Replace names, counts, and text with the project’s exact frame contract.
+
+## Shared Sheet Constraints
+
+```text
+Create a clean sprite sheet on a perfectly flat #ff00ff chroma-key background.
+Strict <cols> columns x <rows> rows grid, exactly <n> centered sprites, unused cells empty.
+Each sprite is fully visible, upright, isolated, and has huge padding inside its cell.
+No cell dividers, no background texture, no watermark, no extra sprites.
+Style: premium casual mobile game UI, cohesive with <theme>, polished 2.5D, readable at in-game size.
+```
+
+## Mahjong Tiles
+
+```text
+Chinese cute Mahjong tile sprite sheet, strict 4 columns x 3 rows.
+Order: wan_1, wan_2, wan_3, tong_1, tong_2, tong_3, tiao_1, tiao_2, tiao_3, gold, back, empty.
+Rounded ivory ceramic faces, emerald green border, large traditional Mahjong symbols, soft bevels.
+No English, no labels outside the tiles, no cropped tiles.
+```
+
+## UI Sheet
+
+```text
+Chinese cute mobile Mahjong UI sprite sheet, strict 3 columns x 3 rows.
+Order: CTA button (no text, red band only), downward tutorial finger icon, gold selection ring, win panel 胜利, lose panel 再试一次, title plaque 麻将对对碰, loading plaque 加载中.
+Keep all plaques aspect-preserving, not stretched, not clipped.
+CTA: moderately wide pill ~2.3:1, fixed round end caps — see references/cta-art-spec.md.
+```
+
+## CTA Button (single override — preferred)
+
+When sheet cell forces an ultra-wide CTA, regenerate as override:
+
+```text
+Single Chinese cute mobile game CTA button on perfectly flat #ff00ff background.
+Aspect ratio about 2.3:1 — moderately wide pill, NOT an ultra-wide banner.
+Fixed ornate left/right gold cloud caps with round green gems; center plain red band.
+Do NOT bake text on the button; runtime overlays 立即下载.
+Circular end caps, huge internal padding, fully visible, no clipping.
+```
+
+## Rewards Sheet
+
+```text
+Chinese cute Mahjong rewards sprite sheet, strict 4 columns x 2 rows.
+Order: 连击 compact plaque, gift icon, 连击开启 toast, 火力全开 toast, 超级连击 toast, 幸运奖励 bonus card, 连击奖励 bonus card, 超级奖励 bonus card.
+Huge padding; long toast plaques must not touch cell edges.
+```
+
+If long toast text clips in a sheet, regenerate that frame as a single-image override:
+
+```text
+Single Chinese cute Mahjong reward toast sprite on perfectly flat #ff00ff background.
+Centered compact horizontal red lacquer plaque with gold trim, text: 连击开启.
+Huge padding around the plaque, no clipping, no stretching, fully visible.
+```
+
+## Digits
+
+```text
+Golden mobile game digit sprite sheet on flat #ff00ff.
+Strict 5 columns x 3 rows. Order: 0,1,2,3,4,5,6,7,8,9,x,:,/.
+Only the symbols, same visual height, readable at 48x64, no labels.
+```
+
+For glow digits:
+
+```text
+Glowing golden digit sprite sheet on flat #ff00ff.
+Strict 5 columns x 2 rows. Order: 0,1,2,3,4,5,6,7,8,9.
+Same visual height and glow weight for every digit.
+```
+
+## FX
+
+```text
+Game FX sprite sheet on flat #ff00ff, strict 3 columns x 2 rows.
+Order: small golden particle orb, vertical sparkle streak, large shard, medium shard, small shard, rounded rectangular selection glow frame.
+Transparent-friendly, crisp edges, no labels.
+```

package/project-templates/phaser/skills/playable-art/references/reference-comparison.md

@@ -0,0 +1,30 @@
+# Reference Comparison
+
+Use this checklist when comparing a playable to reference art.
+
+## Composition
+
+- Identify the three strongest visual anchors in the reference.
+- Check whether the implementation gives the same anchors similar weight.
+- Compare top, middle, and bottom zones separately.
+- Look for dead space, crowded zones, and elements that steal focus.
+
+## Asset Quality
+
+- Reference art often gets quality from thick borders, bevels, highlights, and drop shadows.
+- Code-drawn replacements can fix structure but rarely fully match hand-painted asset quality.
+- If a key object remains weak after code styling, recommend generating or importing a better bitmap asset.
+
+## Common Gaps
+
+- Top HUD is too flat or too thin.
+- CTA is too small or looks like background text.
+- Board pieces are too transparent, causing visual noise.
+- Combo/reward text overlaps badges or particles.
+- Background has decoration but lacks foreground/midground/depth staging.
+
+## Verification
+
+- Compare screenshots at the same viewport.
+- Judge first impression before inspecting details.
+- Check whether the user can immediately identify timer, progress, playable board, and CTA.

package/project-templates/phaser/skills/playable-art/references/sheet-import-v2.md

@@ -0,0 +1,91 @@
+# Sheet Import V2 — Why Elements Were Clipped
+
+## Root Cause (legacy `import-gpt-art-sheets.py`)
+
+1. **Fixed grid + inset shrink** — each cell cropped with `inset` (UI sheet ~44px/side). Wide plaques lose lanterns/tassels/cloud ears.
+2. **`crop_to_alpha(edge_pad=2)` shrinks inward** — trims 2px off each detected edge again.
+3. **Order tied to grid index** — not to actual sprite bounds.
+
+Reference sheets are complete; atlas clips came from import math, not GPT output.
+
+## V2 Pipeline (`import-gpt-art-sheets-v2.py`)
+
+```
+reference/*.png
+  → (1) remove background [WaveSpeed API | chroma fallback]
+  → (2) connected-component blobs (per element)
+  → (3) mark slices: contentBox + safeSliceBox + marked sheet
+  → (4) reading-order sort + drop noise fragments
+  → (5) crop safeSliceBox with outward pad
+  → (6) contain-scale + center in target frame
+  → assets/images/**
+  → npm run build-atlas
+```
+
+## Mark First, Slice Second
+
+V2 now generates deterministic slice evidence before writing sprites:
+
+- `assets/reference/slice-plan.json` — machine-readable slice plan in JSON (JavaScript Object Notation, JavaScript 对象表示法), including `contentBox`, `safeSliceBox`, `contentMarginInsideSafe`, `touchesSourceEdge`, and per-mark `issues[]`.
+- `assets/reference/marked/*-slice-marks.png` — source sheet with red content boxes and green/yellow safe boxes. Yellow means the source is close to a clipping risk.
+
+This gives VLM (Vision-Language Model, 视觉语言模型) review a much clearer target: instead of asking whether the whole sheet “looks okay,” it can inspect each safe slice. The same plan also drives the importer, so the visual mark and the actual crop use the same coordinates.
+
+Run only the marking stage when you want to inspect before slicing:
+
+```bash
+npm run mark:slices
+```
+
+If `slice-plan.json` reports `source_clipped` or `slice_margin_tight`, regenerate the source sheet or add a single-frame override before accepting the import. Do not hide a clipped source by scaling it down after the cut.
+
+## WaveSpeed Background Remover
+
+```bash
+# 推荐：项目根目录 .env（已加入 .gitignore）
+# WAVESPEED_API_KEY=your_key
+
+npm run import:gpt-art
+```
+
+- API: `POST https://api.wavespeed.ai/api/v3/wavespeed-ai/image-background-remover`
+- Cached cleaned sheets: `assets/reference/cleaned/<source>.png`
+- Without API key: falls back to magenta chroma removal
+
+## Commands
+
+```bash
+npm run mark:slices            # mark only, writes no final sprites
+npm run import:gpt-art          # v2 (recommended)
+npm run import:gpt-art:legacy   # old grid importer
+npm run build-atlas
+npm run verify:ui:assets
+```
+
+## When Blob Count Mismatches
+
+Script warns `found N blobs, expected M` and drops smallest fragments. If order wrong:
+
+- Regenerate sheet with clearer magenta gaps between cells
+- Or add single-frame overrides under `assets/reference/`
+
+## Digit Symbols: Colon Shows as `x`
+
+**Symptom:** Timer displays `01x00` instead of `01:00` — `colon.png` contains an `X` graphic.
+
+**Cause:** V2 segmentation splits the colon (`:`) into **two small dot blobs**. Dropping the smallest fragment shifts `x` / `:` / `/` reading order.
+
+**Fix (in `import_gpt_art_pipeline.py`):**
+
+1. `merge_stacked_fragments()` — merge vertically stacked blobs when **both** areas are under ~9000px² and horizontally aligned.
+2. `sort_blobs_reading_order()` — use equal `rows` bands from min/max `cy`, not `cy // max(height)` (avoids bottom-row mis-sort when `x` is 8px lower than colon).
+
+**Verify after import:**
+
+```bash
+# colon.png must be two stacked dots, not X
+open assets/images/digits/colon.png
+npm run build-atlas && npm run build:html
+```
+
+If still wrong, override `assets/images/digits/colon.png` from reference sheet manually, then rebuild atlas.