@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/agents/refs/reviewer-convergence-eval.md

@@ -0,0 +1,130 @@
+# Reviewer: Convergence Evaluation (design_check / ui_diff / load_check)
+
+> **Read before executing any Reviewer mode.** Replaces six-dimension final review in `convergence-v1`.
+> Invoked from `agents/reviewer.md` — orchestrator specifies mode per invoke.
+
+---
+
+## Mode: design_check
+
+Soft checklist only — **do not judge subjective design quality**.
+
+### Gate #1 checklist (PM four docs)
+
+```
+[ ] design-brief exists; Style Direction has Dimension / Modality / Arc
+[ ] layout-spec exists; assetMapping non-empty
+[ ] atom-plan.json exists; skillsMatch non-empty
+[ ] every atom has assignTo + dependsOn
+[ ] no obvious cross-doc contradictions (assetMapping paths align with atoms)
+```
+
+**Fail →** list missing items + `routeTo: pm` (or `designer` if visual doc gap).
+
+### Gate #2b additional checklist
+
+```
+[ ] MC five panels complete (concept + 4 storyboard)
+[ ] MC aspect ratio correct — verify with: playcraft image info <mc-path>
+[ ] ASR dual sheets (UI + element) exist under assets/images/reference/
+[ ] ASR covers main assetMapping element ids
+```
+
+**Pass →** handoff `Run Gate #1` or `Run Gate #2b`. **Fail →** routeTo PM/Designer with specific gaps.
+
+---
+
+## Mode: ui_diff
+
+> **Read `playwright-cli` skill first.** Save all screenshots under `logs/`.
+
+### Procedure
+
+1. Read MC panel paths from `style-exploration.md` / `assets/images/reference/`.
+2. `npm run dev` if devUrl down; read devUrl from `project-state.md`.
+3. For each scene Developer exposed (URL param or UI button):
+
+```bash
+playwright-cli open <devUrl>[?scene=hook|tutorial|endcard|cta]
+playwright-cli resize 390 844
+playwright-cli screenshot --filename=logs/ui-diff-<scene>.png
+```
+
+4. Compare each screenshot vs corresponding MC panel:
+
+| Scene      | MC panel        | Check                                   |
+| ---------- | --------------- | --------------------------------------- |
+| Initial    | Panel 1 Concept | Layout, hierarchy, element completeness |
+| Hook       | Panel 2         | Color mood, hook composition            |
+| Onboarding | Panel 3         | Tutorial UI, low-pressure layout        |
+| EndCard    | Panel 4         | CTA zone, unresolved emotion            |
+| CTA        | Panel 5         | Button prominence, accent color         |
+
+5. `playwright-cli console` — log errors (informational for ui_diff; critical only if UI broken).
+6. `playwright-cli close`.
+
+### UI Diff Report (write to review-report.md)
+
+For each difference:
+
+- Screenshot path + MC reference path
+- Description + severity (`critical` / `major` / `minor`)
+- `routeTo: developer | ta | designer`
+- Fix suggestion
+
+**Pass:** no critical/major diffs (minor logged, do not block).
+**Fail:** `uiReworkRound` +1; handoff orchestrator to `ui_rework`.
+
+### Routing guide
+
+| Issue type                         | routeTo   |
+| ---------------------------------- | --------- |
+| Layout, code binding, scene switch | developer |
+| Wrong asset color/size/style       | ta        |
+| Ambiguous design intent            | designer  |
+
+---
+
+## Mode: load_check
+
+Minimal pre-Gate #3 sanity check — **not gameplay QA**.
+
+### Procedure
+
+1. `npm run dev` if needed; `playwright-cli open <devUrl>`.
+2. Wait for load (≤10s); confirm not white screen.
+3. `playwright-cli console` — fail if any **Error**-level log.
+4. `playwright-cli screenshot --filename=logs/load-check.png`.
+5. `playwright-cli close`.
+
+### Checklist
+
+```
+[ ] Page loads within 10s (not white screen)
+[ ] Console has no Error-level messages
+[ ] game/index.html reachable
+```
+
+**Pass →** `loadCheck: passed`, handoff `Run Gate #3 with devUrl`.
+**Fail →** routeTo Developer with console error summary.
+
+---
+
+## Severity (ui_diff only)
+
+| Severity | Meaning                     | Blocks pass? |
+| -------- | --------------------------- | ------------ |
+| critical | UI broken / missing         | Yes          |
+| major    | Clear visual mismatch vs MC | Yes          |
+| minor    | Polish / slight drift       | No (log)     |
+
+---
+
+## project-state fields (Reviewer writes)
+
+| Field            | Mode         | Values                    |
+| ---------------- | ------------ | ------------------------- |
+| `uiReviewStatus` | ui_diff      | pending / passed / failed |
+| `uiReworkRound`  | ui_diff fail | 0–5                       |
+| `loadCheck`      | load_check   | pending / passed / failed |
+| `loadCheckNotes` | load_check   | console + load summary    |

package/project-template/.claude/agents/refs/reviewer-six-dimension-eval.md

@@ -0,0 +1,6 @@
+# Reviewer: Six-Dimension Evaluation (deprecated)
+
+> **Superseded by [`reviewer-convergence-eval.md`](./reviewer-convergence-eval.md)** in `convergence-v1`.
+> Do not use six-dimension scoring or final `review`/`rework` stages.
+
+See `agents/reviewer.md` for the three modes: `design_check`, `ui_diff`, `load_check`.

package/project-template/.claude/agents/refs/ta-3d-flip-recipe.md

@@ -0,0 +1,85 @@
+# TA 3D Flip & Material Reskin Recipe
+
+> Read by Technical Artist when dealing with:
+> - Material/texture swap while preserving symbols (mahjong white→ice/metal/wood)
+> - Card/tile flip animations (16-frame sprite sheets)
+> - Any task requiring the 3D white model pipeline
+
+---
+
+## Option C: Material Reskin — Preserve Symbols, Swap Base Texture
+
+**THE most common TA task for sprite sheet style variants.**
+- Use when: mahjong white→ice, white→metal, white→wood
+- Key insight: symbols are face textures, base material is a separate layer
+
+```bash
+# Step 1: Split the original sprite sheet into individual tiles
+playcraft image sprite-split \
+  --input assets/images/tiles/original_sheet.png \
+  --output-dir assets/images/tiles/split_frames \
+  --auto-detect --hint "mahjong tiles, uniform grid"
+# → 44 individual PNGs + split-meta.json
+
+# Step 2: Generate ONE new base material texture (reused for all tiles)
+playcraft tools generate-image \
+  --prompt "ice crystal frosted glass texture, blue-white cold, seamless, top-down" \
+  --output assets/textures/ice_base.png
+
+# Step 3: Create white model with new base material
+playcraft 3d apply-texture \
+  --model plane \
+  --texture assets/textures/ice_base.png \
+  --output assets/models/ice_tile_base.glb
+
+# Step 4: For EACH tile — render white model + original symbol as face texture
+# (Uses the software rasterizer from playcraft-3d-flip-sprite SKILL)
+# face texture = the split frame from Step 1 (preserves symbol exactly)
+node render.mjs assets/models/ice_tile_base.glb \
+  assets/images/tiles/reskinned/tile_001.png \
+  assets/images/tiles/split_frames/frame_r0_c0.png
+# Repeat for all 44 tiles — write a ta-workspace script for this step
+
+# Step 5: Reassemble into sprite sheet (same grid as original)
+playcraft image sprite-sheet \
+  --inputs assets/images/tiles/reskinned/tile_001.png,tile_002.png,... \
+  --output assets/images/tiles/ice_sheet \
+  --columns <original_columns> \
+  --cell-width <W> --cell-height <H>
+```
+
+**Style switching efficiency**:
+- To switch to METAL: only redo Step 2 (new texture) + Step 3-5
+- To switch to WOOD: same — just one new base texture
+- Symbols never change, never touch AI regeneration
+
+---
+
+## Option D: Batch 3D Flip Sprite Sheet (e.g., 34 mahjong flip animations)
+
+Read `playcraft-3d-flip-sprite` SKILL for the full rendering pipeline.
+(Software rasterizer: no Puppeteer/headless-gl needed)
+
+**Per-tile workflow**: white model GLB + face texture → 16-frame flip sprite sheet
+
+```
+1. Flatten base GLB (remove surface geometry of original design)
+2. Generate face texture per tile variant
+3. Render 16-frame flip animation with soft rasterizer
+4. Output sprite sheet PNG
+```
+
+See `.claude/skills/playcraft-3d-flip-sprite/` for complete instructions.
+
+---
+
+## Mahjong Tile Example: All 4 Workflows Compared
+
+| Scenario | Method | When |
+|---------|--------|------|
+| One concept mockup → all 34 tiles | Sprite Generation (AI batch with reference-image) | Starting from scratch |
+| Existing white tiles → Ice style (symbols preserved) | 3D path (Option C above) | Material/texture swap |
+| Existing white tiles → Metal style | 3D path (swap ice→metal texture, rerun Step 3-5) | Style variant |
+| Existing tiles → Pixel art style (symbols redrawn) | Sprite Remix (per-frame AI) | Full creative restyle |
+| Existing tiles → Darker mood | Image Processing (`tint` + `overlay`) | Color/mood shift |
+| Flip animation (16 frames per tile) | Option D (3D flip sprite, playcraft-3d-flip-sprite SKILL) | Animation |

package/project-template/.claude/agents/refs/ta-atlas-deliverable-standard.md

@@ -0,0 +1,67 @@
+# TA Atlas Deliverable Standard
+
+> **When**: `stage: production` branch in `technical-artist.md` § Runtime.  
+> **Contract source**: `layout-spec.md` atlas groups + `assetMapping` (Gate #1 locked).
+
+## Defaults
+
+| Asset type          | Delivery format                                                                              |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| Runtime images      | **WebP** (`.webp`) — not PNG for final runtime assets                                        |
+| Multi-element class | **One atlas per logical group** → `.webp` + `.json` sidecar (`playcraft image sprite-sheet`) |
+| Single large asset  | One `.webp` (full-screen bg, etc.)                                                           |
+| Audio (BGM/SFX)     | **MP3** only after TA post-process                                                           |
+| Digit strip         | Single horizontal **WebP** at `layout-spec` path (not merged into UI atlas)                  |
+
+## Atlas grouping rules
+
+1. Read PM's **atlas grouping table** in `layout-spec.md` (group name → elementIds → `atlasPath`).
+2. **≥2 elements in same group** → TA MUST deliver **one** `.webp` + `.json`; map each element via `frameId` in assetMapping.
+3. **Do not** split one group into scattered files.
+4. **Exceptions** (single file OK): full-screen background, digit strip, MC/ASR reference (non-runtime), animation-only atlases (one animation = one atlas).
+
+## Production pipeline
+
+1. Spec Quick-Check → Style Interpretation → micro-batch (≥3) per group.
+2. Batch generate frames → `playcraft image sprite-sheet` → convert to **WebP** if needed:
+   ```bash
+   playcraft image convert --input atlas.png --output assets/images/tiles/tiles_atlas.webp --quality 85
+   ```
+3. Validate sidecar JSON: frame count = element count in group; grid params in `ta-log.md`.
+4. Audio: Designer MP3 → `playcraft audio compress/trim/loop/fade` → output **MP3**; verify with `playcraft audio info`.
+
+## Transparency requirements
+
+| Asset category                | Alpha required | Chroma key strategy                                  | Post-verify                               |
+| ----------------------------- | -------------- | ---------------------------------------------------- | ----------------------------------------- |
+| UI overlay (icons, text, HUD) | ✅ channels=4  | Per color conflict matrix (see ta-pipeline-cookbook) | Dark-bg overlay verify (no white/residue) |
+| VFX atlas (glow, particles)   | ✅ channels=4  | Blue screen #0000FF (VFX常含金/橙色)                 | Per-frame dark-bg verify                  |
+| Game element atlas (tiles)    | ✅ channels=4  | Per color conflict matrix                            | Dark-bg overlay verify                    |
+| Card/board piece (rect body)  | ❌ opaque OK   | N/A (white bg is part of the asset)                  | N/A                                       |
+| Full-screen background        | ❌ opaque OK   | N/A                                                  | Edge-to-edge full-coverage check          |
+| Digit strip                   | ✅ channels=4  | Blue screen #0000FF (digits often gold/white)        | Dark-bg overlay verify                    |
+
+**Color conflict matrix** — choose chroma key color to avoid edge residue:
+
+- Gold/yellow/orange/green assets → **blue screen #0000FF** (never green)
+- Blue/purple assets → **green screen #00FF00** (never blue)
+- Multi-color/rainbow → **magenta #FF00FF** (last resort)
+- All others → green screen #00FF00 (default)
+
+## Compliance (TA)
+
+| Check           | Pass criteria                                                                  |
+| --------------- | ------------------------------------------------------------------------------ |
+| Atlas coverage  | Every runtime element resolves to atlas+frame or single webp path              |
+| Sidecar         | `.json` exists beside each multi-element atlas                                 |
+| Format          | WebP for images; MP3 for audio (unless layout-spec explicit exception)         |
+| ta-log          | One manifest row per atlas group: path, frames, cols/frameW/frameH/frameCount  |
+| **Alpha check** | All transparent assets have `channels=4` (verified via `playcraft image info`) |
+| **Dark-bg OK**  | All transparent assets pass dark-background (#1A1A2E) overlay — no residue     |
+| **BG coverage** | Full-screen backgrounds: edge-to-edge, no fade/vignette/white corners          |
+
+## Developer handoff
+
+Developer loads `atlasPath` once, uses `frameId` from layout-spec / JSON — not per-element file paths for grouped assets.
+
+See also: `ta-pipeline-cookbook.md`, `playcraft-sprite-generation` SKILL (final delivery extension = `.webp`).

package/project-template/.claude/agents/refs/ta-batch-pipeline-recipes.md

@@ -0,0 +1,120 @@
+> 本文件是 batch/pipeline 的实用配方集。选型决策树和基础语法见 `playcraft-batch-pipeline` skill。
+
+# Batch / Pipeline 实用配方集
+
+---
+
+## Batch 配方
+
+### 批量 resize + 转换格式
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw_tiles/ \
+  --output-dir assets/images/tiles/ \
+  --glob "*.png" \
+  --steps "resize --width 128 --height 128, trim" \
+  --parallel 8
+```
+
+### 批量去背（绿幕）
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw_sprites/ \
+  --output-dir assets/images/sprites/ \
+  --steps "remove-background --method floodfill --tolerance 40" \
+  --parallel 4
+```
+
+### 批量统一色调（制作主题变体）
+
+```bash
+# 生成蓝色主题版本
+playcraft image batch \
+  --input-dir assets/images/tiles/ \
+  --output-dir assets/images/tiles_blue_theme/ \
+  --steps "tint --color #4466BB" \
+  --parallel 6
+```
+
+### 断点续传（大批量任务中断后恢复）
+
+```bash
+# 第一次运行中断了
+playcraft image batch \
+  --input-dir assets/images/raw/ \
+  --output-dir assets/images/processed/ \
+  --steps "resize --width 256 --height 256, grayscale" \
+  --parallel 4 \
+  --skip-existing    # 再次运行时跳过已完成的文件
+```
+
+---
+
+## Pipeline 配方
+
+### 配方 A: 去背 + 统一尺寸 + 合并精灵图
+
+```yaml
+# ta-workspace/tile_pipeline.yaml
+input:
+  dir: assets/images/raw_tiles/
+  glob: "*.png"
+
+steps:
+  - command: remove-background
+    method: floodfill
+    tolerance: 40
+  - command: trim
+    threshold: 10
+  - command: resize
+    width: 128
+    height: 128
+  - command: pad
+    all: 4
+
+output:
+  dir: ta-workspace/tmp/tiles_processed/
+
+assemble:
+  sprite-sheet:
+    output: assets/images/tiles_atlas
+    columns: 6
+    padding: 2
+```
+
+```bash
+playcraft image pipeline --config ta-workspace/tile_pipeline.yaml
+```
+
+### 配方 B: 多个主题色版本
+
+为同一套素材生成不同色调的主题变体：
+
+```bash
+# 蓝色主题
+playcraft image pipeline --config ta-workspace/theme_blue.yaml
+
+# 红色主题（修改 tint color 即可）
+sed 's/#4466BB/#BB4444/' ta-workspace/theme_blue.yaml > ta-workspace/theme_red.yaml
+playcraft image pipeline --config ta-workspace/theme_red.yaml
+```
+
+### 配方 C: 批量缩略图生成
+
+```yaml
+input:
+  dir: assets/images/concept/
+  glob: "*.png"
+steps:
+  - command: resize
+    width: 240
+    height: 240
+    fit: cover
+  - command: convert
+    format: webp
+    quality: 80
+output:
+  dir: assets/images/thumbnails/
+```