@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/phaser/skills/playable-art/scripts/verify-alpha-clean.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Verify transparent asset alpha channel and common matte residue symptoms."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+
+def residue_counts(rgb: np.ndarray, mask: np.ndarray) -> dict[str, int]:
+    if not np.any(mask):
+        return {"green": 0, "blue": 0, "magenta": 0, "white": 0, "black": 0}
+    r = rgb[:, :, 0]
+    g = rgb[:, :, 1]
+    b = rgb[:, :, 2]
+    return {
+        "green": int(np.sum(mask & (g > 180) & (r < 120) & (b < 140))),
+        "blue": int(np.sum(mask & (b > 180) & (r < 140) & (g < 160))),
+        "magenta": int(np.sum(mask & (r > 180) & (b > 180) & (g < 130))),
+        "white": int(np.sum(mask & (r > 235) & (g > 235) & (b > 235))),
+        "black": int(np.sum(mask & (r < 18) & (g < 18) & (b < 18))),
+    }
+
+
+def verify(path: Path, max_residue_ratio: float) -> dict:
+    img = Image.open(path)
+    report = {
+        "path": str(path),
+        "mode": img.mode,
+        "width": img.width,
+        "height": img.height,
+        "ok": True,
+        "failures": [],
+        "warnings": [],
+        "recommendations": [],
+    }
+    if "A" not in img.getbands():
+        report["ok"] = False
+        report["failures"].append("missing alpha channel")
+        report["recommendations"].append("route to playable-art; use chroma, dual-bg-diff, or rgb-alpha-split")
+        return report
+
+    rgba = np.asarray(img.convert("RGBA"))
+    rgb = rgba[:, :, :3]
+    alpha = rgba[:, :, 3]
+    opaque = int(np.sum(alpha == 255))
+    transparent = int(np.sum(alpha == 0))
+    partial_mask = (alpha > 0) & (alpha < 255)
+    edge_mask = (alpha > 0) & (alpha < 250)
+    report["alpha"] = {
+        "opaquePixels": opaque,
+        "transparentPixels": transparent,
+        "partialPixels": int(np.sum(partial_mask)),
+    }
+
+    if opaque + int(np.sum(partial_mask)) == 0:
+        report["ok"] = False
+        report["failures"].append("alpha channel is fully transparent")
+    if transparent == 0:
+        report["ok"] = False
+        report["failures"].append("alpha channel has no transparent pixels")
+        report["recommendations"].append("route to playable-art; extract a matte before atlas import")
+
+    counts = residue_counts(rgb, edge_mask)
+    report["residueCounts"] = counts
+    edge_total = max(int(np.sum(edge_mask)), 1)
+    bad = {k: v for k, v in counts.items() if v / edge_total > max_residue_ratio}
+    if bad:
+        report["ok"] = False
+        report["failures"].append(f"edge residue above threshold: {bad}")
+        if any(k in bad for k in ("green", "blue", "magenta")):
+            report["recommendations"].append("route to playable-art; switch chroma color or use rgb-alpha-split")
+        if "white" in bad:
+            report["recommendations"].append("route to playable-art; use dual-bg-diff or rgb-alpha-split for antialiasing")
+        if "black" in bad:
+            report["recommendations"].append("route to playable-fx-peak for black-add if this is glow VFX")
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", type=Path)
+    parser.add_argument("--max-residue-ratio", type=float, default=0.08)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    report = verify(args.image, args.max_residue_ratio)
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        status = "PASS" if report["ok"] else "FAIL"
+        print(f"[alpha-clean] {status}: {args.image}")
+        for failure in report["failures"]:
+            print(f"  - {failure}")
+        for recommendation in report["recommendations"]:
+            print(f"  recommendation: {recommendation}")
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,116 @@
+---
+name: playable-debug
+description: >-
+  Step ⑤ auto-clear for playables. Agent checks game-config before record:mp4
+  in video-validate-loop. Use when record fails to reach ENDCARD or user mentions
+  一键通关. Usually invoked by other skills, not directly by user.
+---
+
+# Playable Debug Playback
+
+> **通常由 video-validate-loop / record-playback 在录屏前调用**，用户不单独跑。
+
+---
+
+## Agent 入口（录屏前 checklist）
+
+### 1. 开发态录屏配置
+
+`game/config/game-config.ts`（或 legacy `.js`）：
+
+| Key                 | 录屏优化时  |
+| ------------------- | ----------- |
+| `SHOW_DEBUG_BUTTON` | **`true`**  |
+| `SKIP_TRANSITIONS`  | **`false`** |
+
+### 2. 验证可达 ENDCARD
+
+**Pass 标准**：`window.__playable.autoPlay()` + `getState().currentPhase === 'ENDCARD'`（见 `npm run verify:contract`）。
+
+Legacy 链路：`DebugButton` → `_onDebugAutoPlay()` → `autoPlayToWin()` → ENDCARD（仍可用，2026-Q3 移除）。
+
+录屏脚本优先调用 `__playable.autoPlay()`；legacy 项目走 `evaluate _onDebugAutoPlay()`。
+
+### 3. 发布前（build:html 前）
+
+反向：`SHOW_DEBUG_BUTTON: false`，写进 validate 报告「发布配置已关 debug」。
+
+---
+
+## When to Apply
+
+- 「一键通关」按钮不见了
+- 需要快速跑完整局验证 end card / CTA / 动画
+- 发布前检查调试项是否关闭
+- 自动玩卡住、与教程/guide 冲突
+
+## Config Switches (`game-config.js`)
+
+| Key                 | 开发             | 发布        |
+| ------------------- | ---------------- | ----------- |
+| `SHOW_DEBUG_BUTTON` | `true`           | **`false`** |
+| `SKIP_TRANSITIONS`  | 可选 `true` 加速 | `false`     |
+| `IS_EASY_MODE`      | 按需             | 按产品      |
+
+`SHOW_DEBUG_BUTTON: false` 时 **不会创建** `DebugButton`（不是隐藏，是 `null`）。
+
+## 一键通关链路
+
+```
+publishPlayableRuntime()  →  window.__playable.autoPlay()  →  ENDCARD   ← pass 标准
+       ↓ (legacy warn)
+game-config.ts  SHOW_DEBUG_BUTTON
+       ↓
+main-scene.js   DebugButton → _onDebugAutoPlay()
+       ↓
+match-system.js autoPlayToWin()
+       ↓
+sceneManager    通关 → ENDCARD
+```
+
+**按钮位置**：`GAME_CONFIG.DEBUG`（由 `applySafeLayout` 写在 CTA 上方左侧）。
+
+**相关文件**
+
+- `game/gameplay/debug-tools.js` — `DebugButton` UI
+- `game/scenes/main-scene.js` — `_onDebugAutoPlay`, `_prepareDebugAutoPlay`
+- `game/gameplay/match-system.js` — `autoPlayToWin`
+
+## 恢复一键通关
+
+1. 确认 `SHOW_DEBUG_BUTTON: true`
+2. 确认 `index.html` 已加载 `debug-tools.js`（在 `main-scene.js` 之前）
+3. 刷新页面；按钮在左下、CTA 上方
+4. 若仍无：检查是否已进入 `ENDCARD`（`setEnabled(false)` 会隐藏）
+
+## 自动玩行为
+
+`autoPlayToWin`：
+
+1. 跳过教程 / `disableTutorialMode`
+2. 循环 `findMatchablePair` 正常消除
+3. 死局后静默扫尾
+4. `board.isAllMatched()` 后结束
+
+`setBusy(true)` 期间按钮文案为「自动玩…」，结束后恢复。
+
+## 发布前检查
+
+```bash
+rg "SHOW_DEBUG_BUTTON:\s*true" game/config/game-config.js && echo "WARN: disable debug"
+```
+
+必做：
+
+- [ ] `SHOW_DEBUG_BUTTON: false`
+- [ ] `SKIP_TRANSITIONS: false`（除非产品要求）
+- [ ] 浏览器目视无绿色调试按钮
+
+## Related Skills
+
+- [playable-validate](../playable-validate/SKILL.md) — 录屏 validate、[validation-rules §⑥](../playable-validate/validation-rules.md)
+- [playable-verify-ui](../playable-verify-ui/SKILL.md) — verify:ui / layout
+
+## References
+
+- 配置与接入：[references/debug-config.md](references/debug-config.md)

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Playable Debug Playback'
+  short_description: 'Restore and manage playable debug auto-play.'
+  default_prompt: 'Restore or configure playable debug controls including one-click auto-clear and pre-ship flag checks.'

package/project-templates/phaser/skills/playable-debug/references/debug-config.md

@@ -0,0 +1,40 @@
+# Debug Config Reference
+
+## MainScene 接入
+
+```js
+this.debugButton = GAME_CONFIG.SHOW_DEBUG_BUTTON
+  ? new DebugButton(this, () => this._onDebugAutoPlay())
+  : null;
+```
+
+ENDCARD 时禁用：
+
+```js
+if (this.debugButton) this.debugButton.setEnabled(false);
+```
+
+点击穿透：board 点击前先判断 `debugButton.contains(x, y)`。
+
+## DEBUG 布局块
+
+```js
+DEBUG: { W: 120, H: 40, X: 0, Y: 0 }  // X/Y 由 applySafeLayout 写入
+```
+
+默认位置：安全区左侧，连击条上方。
+
+## \_prepareDebugAutoPlay 要点
+
+- `pairGuide.skip()` 若教程激活
+- `matchSystem.disableTutorialMode()`
+- 显示 HUD / 启动 countdown（若尚未开始）
+
+## 扩展调试能力
+
+新增调试按钮时：
+
+1. 增加 `SHOW_*` 开关，默认 `false`
+2. 在 `applySafeLayout` 派生坐标，勿硬编码 Y
+3. 发布检查脚本加入 `rg` 规则
+4. depth ≥ 500，避免被 board 遮挡

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

@@ -0,0 +1,148 @@
+---
+name: playable-focus
+description: >-
+  L→G local-to-global validation for playables. Agent MUST run ensure-project
+  first, then bootstrap if needed, sweep L1/G1 or record clean/integration ids.
+  Use when user asks to optimize a specific FX spec, run focus lab, or narrow
+  validation before full MP4. User never runs bootstrap manually.
+---
+
+# Playable Focus Playground
+
+> **用户**：「用 focus playground 优化 clean:frame:xxx / 做 L1 sweep」  
+> **Agent**：ensure-project → 本入口 → record/sweep → focus 报告。
+
+---
+
+## Agent 入口
+
+### 0. 自举
+
+```bash
+npm run ensure:project
+```
+
+无 `playground/registry.json` 时 ensure 已 bootstrap；仍缺则：
+
+```bash
+npm run bootstrap:playground
+```
+
+### 1. 解析用户目标 → playground id
+
+| 用户说             | id                                      |
+| ------------------ | --------------------------------------- |
+| match_burst / 祥云 | `clean:frame:match_burst_v2`            |
+| shard / 碎裂粒子   | `clean:particle:shard_debris`           |
+| 消牌合成           | `integration:EVENT:match-once`          |
+| ENDCARD            | `integration:PHASE:endcard-win`         |
+| 整片               | `flow:full`（交给 video-validate-loop） |
+
+`npm run playground -- list` 列全部 id。
+
+### 2. Frame spec 额外 gate（ADD 光效）
+
+```bash
+npm run validate:frame-anchors -- 'assets/images/fx/<name>_frame*.png' --json validate/focus/frame/<name>-anchor.json
+```
+
+FAIL → `playable-fx-peak` repack 后重跑。
+
+### 3. 录屏
+
+```bash
+npm run playground -- record <id> --headed
+# 或批量
+npm run sweep:L1 -- --headed
+npm run sweep:G1 -- --headed
+```
+
+### 4. 报告
+
+`validate/focus/` 或 `validate/sweep/L1-*.md` — 须有 P0/P1 结论，禁止只写「录屏 ok」。
+
+### 5. 卷到整片（G 步）
+
+L1 PASS 后：`integration:EVENT:match-once` 或 `npm run record:mp4` 做 G1/G2。
+
+---
+
+## When to Apply
+
+- 新项目首次接入 playground / focus-lab
+- L1 clean spec 穷举、sweep L1/G1
+- Integration：`match-once`、`endcard-win`
+- 需要 **比整片 MP4 更窄** 的验收输入
+
+## Bootstrap（一次性）
+
+在 playable 工程根（如 `testN/`）：
+
+```bash
+node ../skills/playable-focus/scripts/bootstrap-playground.mjs
+```
+
+复制：
+
+- `focus-lab/` — frame/particle harness（依赖项目内 `game/frame-fx.js` 等）
+- `playground/registry.json` — integration + flow
+- `playground/vfx-catalog.json` — clean spec 穷举表
+
+已存在则 skip；`--force` 覆盖。
+
+## CLI
+
+```bash
+# 在 testN/ 下，package.json 已配置时可：
+npm run playground -- list
+npm run playground -- record clean:frame:match_burst_v2 --headed
+npm run playground -- sweep L1
+npm run playground -- sweep G1
+```
+
+直接调用：
+
+```bash
+node ../skills/playable-focus/scripts/playground.mjs --root=. list
+node ../skills/playable-focus/scripts/playground.mjs --root=. sweep L1 --headed
+```
+
+## Clean id 格式
+
+```
+clean:<renderType>:<specId>
+  clean:frame:match_burst_v2
+  clean:particle:shard_debris
+```
+
+Integration / Flow 见 `playground/registry.json`。
+
+## L1 / G1 Exit（与 validation-rules 对齐）
+
+**L1 PASS** 需同时：
+
+- [ ] sweep 录屏成功（manifest 无 fail）
+- [ ] frame spec：`validate-frame-anchors.py` PASS
+- [ ] decompose spec：语义 checklist（见 decompose-fx examples）
+- [ ] focus 报告非空结论（非「录屏 ok」敷衍）
+
+**G1 PASS**：
+
+- [ ] `integration:EVENT:match-once` 无新 P0
+- [ ] `integration:PHASE:endcard-win` 无新 P0
+
+## 辅助脚本
+
+```bash
+# 从 sweep manifest 抽帧
+node ../skills/playable-focus/scripts/extract-focus-frames.mjs recordings/sweep/L1-*/manifest.json
+
+# 生成 focus 报告骨架
+node ../skills/playable-focus/scripts/generate-focus-reports.mjs
+```
+
+## 相关
+
+- [validation-rules.md](../playable-validate/validation-rules.md)
+- [docs/playground-construction.md](../../docs/playground-construction.md)
+- [docs/local-playground.md](../../docs/local-playground.md)

package/project-templates/phaser/skills/playable-focus/scripts/bootstrap-playground.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Copy focus-lab harness + playground templates into a playable project.
+ * Safe: skips files that already exist unless --force.
+ *
+ * Usage (from testN/):
+ *   node ../skills/playable-focus/scripts/bootstrap-playground.mjs
+ *   node ../skills/playable-focus/scripts/bootstrap-playground.mjs --force
+ */
+
+import { copyFile, mkdir, readdir, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(__dirname, '../templates');
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), force: false };
+  for (const arg of argv) {
+    if (arg === '--force') opts.force = true;
+    else if (arg.startsWith('--root=')) {
+      const v = arg.slice(7);
+      opts.root = v.startsWith('/') ? v : join(process.cwd(), v);
+    }
+  }
+  return opts;
+}
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyTree(srcDir, destDir, force) {
+  await mkdir(destDir, { recursive: true });
+  const entries = await readdir(srcDir, { withFileTypes: true });
+  for (const ent of entries) {
+    const src = join(srcDir, ent.name);
+    const dest = join(destDir, ent.name);
+    if (ent.isDirectory()) {
+      await copyTree(src, dest, force);
+    } else if (force || !(await exists(dest))) {
+      await copyFile(src, dest);
+      console.log(`[bootstrap] ${dest.replace(process.cwd() + '/', '')}`);
+    } else {
+      console.log(`[bootstrap] skip (exists): ${dest.replace(process.cwd() + '/', '')}`);
+    }
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = opts.root;
+
+  console.log(`[bootstrap] project root: ${root}`);
+
+  await copyTree(join(TEMPLATES, 'focus-lab'), join(root, 'focus-lab'), opts.force);
+
+  await mkdir(join(root, 'playground'), { recursive: true });
+
+  const registryDest = join(root, 'playground/registry.json');
+  if (opts.force || !(await exists(registryDest))) {
+    await copyFile(join(TEMPLATES, 'playground/registry.template.json'), registryDest);
+    console.log('[bootstrap] playground/registry.json');
+  }
+
+  const catalogDest = join(root, 'playground/vfx-catalog.json');
+  if (opts.force || !(await exists(catalogDest))) {
+    await copyFile(join(TEMPLATES, 'playground/vfx-catalog.template.json'), catalogDest);
+    console.log('[bootstrap] playground/vfx-catalog.json');
+  }
+
+  console.log('[bootstrap] done. Requires game/frame-fx.js + anim-config in project.');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/project-templates/phaser/skills/playable-focus/scripts/extract-focus-frames.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Extract 3-5 frames from focus/sweep mp4s for validate reports.
+ * Usage: node scripts/extract-focus-frames.mjs <manifest.json>
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { dirname, join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+
+function run(cmd, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} exit ${code}`))));
+  });
+}
+
+async function probeDuration(mp4Path) {
+  const { spawnSync } = await import('node:child_process');
+  const out = spawnSync('ffprobe', [
+    '-v', 'error', '-show_entries', 'format=duration',
+    '-of', 'default=noprint_wrappers=1:nokey=1', mp4Path
+  ], { encoding: 'utf8' });
+  return parseFloat(out.stdout.trim()) || 3;
+}
+
+async function extractFrames(mp4Path, outDir, count = 4, loopMs = 1800) {
+  await mkdir(outDir, { recursive: true });
+  const dur = await probeDuration(mp4Path);
+  const warmup = 0.4;
+  const peaks = [];
+  for (let i = 0; i < count; i++) {
+    const loopIdx = Math.floor(i / 2);
+    const offset = i % 2 === 0 ? 0.15 : 0.35;
+    peaks.push(warmup + loopIdx * (loopMs / 1000) + offset);
+  }
+  for (let i = 0; i < peaks.length; i++) {
+    const t = Math.min(peaks[i], dur - 0.05);
+    const out = join(outDir, `f${String(i + 1).padStart(2, '0')}.jpg`);
+    await run('ffmpeg', ['-y', '-ss', String(t), '-i', mp4Path, '-frames:v', '1', '-q:v', '2', '-update', '1', out]);
+  }
+}
+
+async function main() {
+  const manifestPath = process.argv[2];
+  if (!manifestPath) {
+    console.error('Usage: node scripts/extract-focus-frames.mjs <manifest.json>');
+    process.exit(1);
+  }
+
+  const absManifest = manifestPath.startsWith('/') ? manifestPath : join(ROOT, manifestPath);
+  const manifest = JSON.parse(await readFile(absManifest, 'utf8'));
+
+  const catalog = JSON.parse(await readFile(join(ROOT, 'playground', 'vfx-catalog.json'), 'utf8'));
+
+  for (const entry of manifest.entries) {
+    if (entry.status !== 'ok' || !entry.mp4) continue;
+    const mp4 = join(ROOT, entry.mp4);
+    const type = entry.renderType || 'integration';
+    const spec = entry.specId || entry.id.split(':').pop();
+    const outDir = join(ROOT, 'validate', 'focus', type, 'frames', spec);
+    const typeMeta = catalog.renderTypes[type];
+    const loopMs = typeMeta?.loopMs || 1800;
+    console.log(`[frames] ${entry.id} → ${outDir.replace(ROOT + '/', '')}`);
+    await extractFrames(mp4, outDir, 4, loopMs);
+    entry.framesDir = outDir.replace(ROOT + '/', '');
+  }
+
+  await writeFileFixed(absManifest, JSON.stringify(manifest, null, 2));
+  console.log('[frames] Done');
+}
+
+async function writeFileFixed(path, data) {
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(path, data);
+}
+
+main().catch((e) => {
+  console.error('[frames]', e.message);
+  process.exit(1);
+});