@playcraft/cli 0.0.44 → 0.0.46

package/project-template/skills/playable-verify-ui/profiles/template.profile.yaml

@@ -0,0 +1,84 @@
+# Copy to project root as playable.ui.profile.yaml and fill in.
+meta:
+  engine: phaser3
+  name: my-playable
+  design:
+    width: 1080
+    height: 1920
+
+paths:
+  # Single source of truth. verify:ui loads TS directly via esbuild (.js also works).
+  gameConfig: game/config/game-config.ts
+  indexHtml: game/index.html
+  assetsRoot: assets/images
+  atlasRoot: assets/atlas
+  assetNamingDoc: docs/asset-naming.md
+  buildAtlasScript: scripts/build-atlas.py
+  fetchAssetsScript: scripts/fetch-assets.sh
+
+safeArea:
+  minTop: 48
+  minBottom: 48
+  minSide: 16
+
+assets:
+  standalone:
+    - key: bg
+      path: bg.png
+      width: 1080
+      height: 1920
+  atlases:
+    - name: ui
+      json: ui.json
+      png: ui.png
+      frames:
+        - name: ui_cta_btn
+          source: ui/cta_btn.png
+          width: 500
+          height: 80
+
+layout:
+  configKeys:
+    - SAFE_TOP
+    - SAFE_BOTTOM
+    - PLAY_AREA_TOP
+    - PLAY_AREA_BOTTOM
+    - CTA_Y
+    - CTA_H
+  regions:
+    hud:
+      y0: 'HUD.BAR_Y'
+      y1: 'HUD.BAR_Y + HUD.BAR_H'
+    cta:
+      y0: 'CTA_Y'
+      y1: 'CTA_Y + CTA_H'
+    playArea:
+      y0: 'PLAY_AREA_TOP'
+      y1: 'PLAY_AREA_BOTTOM'
+  rules:
+    - type: safe_top
+      region: hud
+      min: 'safeArea.minTop'
+    - type: ordered
+      first: playArea
+      second: cta
+
+antipatterns:
+  - id: hardcoded_cta_y
+    grep: "CTA_Y:\\s*1[56]\\d{2}"
+    paths: ['game/**/*.js', 'game/**/*.ts']
+    exclude: ['game/config/game-config.js', 'game/config/game-config.ts']
+    severity: warn
+
+scripts:
+  loadOrder:
+    - config/game-config.ts
+
+thresholds:
+  maxAtlasSheetKb: 512
+  maxStandaloneKb: 256
+  maxTotalAssetsMb: 8
+
+modules:
+  boardBounds: false
+  matchShatter: false

package/project-template/skills/playable-verify-ui/reference.md

@@ -0,0 +1,165 @@
+# Playable UI Profile — Reference
+
+## Schema 概览
+
+Profile 文件：`playable.ui.profile.yaml`（项目根目录）
+
+校验：`skills/playable-verify-ui/schema/playable-ui-profile.schema.json`
+
+| 段                  | 必填 | 说明                                                |
+| ------------------- | ---- | --------------------------------------------------- |
+| `meta.engine`       | ✓    | `phaser3` / `cocos` / `pixi`（首版仅 phaser3 检测） |
+| `meta.design`       | ✓    | 设计分辨率 width × height                           |
+| `paths`             | ✓    | gameConfig、indexHtml、assetsRoot、atlasRoot        |
+| `safeArea`          | ✓    | minTop / minBottom / minSide                        |
+| `assets`            | ✓    | standalone + atlases[].frames                       |
+| `layout`            | ✓    | configKeys、regions、rules                          |
+| `antipatterns`      |      | grep 规则列表                                       |
+| `scripts.loadOrder` |      | index.html script 顺序子序列                        |
+| `thresholds`        |      | 包体预算 KB/MB                                      |
+| `modules`           |      | 可选功能标签（boardBounds、matchShatter 等）        |
+
+---
+
+## asset-manifest（结构化资产契约）
+
+文件：`assets/asset-manifest.json`（项目根目录下），由 TA（Technical Artist，技术美术）**手写**，校验器把关。
+
+校验：`schema/asset-manifest.schema.json`；示例：`examples/asset-manifest.example.json`。
+
+test11 的根因不是底层图像工具坏了，而是**工具之间缺结构化契约**——没人声明某张图到底是 runtime 背景、CTA、tile，还是 reference-only 成品稿，也没声明哪些文字是屏上合法的。manifest 把这层口径固定下来，视觉门按 `role` / `usage` / `roi` / `allowedText` 消费，而不是靠猜。
+
+字段（`assets` 的 key 必须是 **numericId**，纯数字）：
+
+| 字段          | 必填 | 说明                                                                                                     |
+| ------------- | ---- | -------------------------------------------------------------------------------------------------------- |
+| `path`        | ✓    | 资产相对项目根的路径；不存在 = 对账失败（stale manifest）                                                |
+| `role`        | ✓    | `background` / `tile` / `cta` / `logo` / `decoration` / `character` / `prop` / `ui` / `fx` / `reference` |
+| `usage`       |      | `runtime`（默认）/ `reference-only`（参考图，不参与运行时质量门）                                        |
+| `roi`         |      | 归一化 ROI，`name -> [x1,y1,x2,y2]`，0..1 且 x1<x2,y1<y2                                                 |
+| `allowedText` |      | 该资产上合法文字白名单                                                                                   |
+
+顶层 `screen.allowedText`：屏级合法文字白名单（CTA 文案等）。
+
+**门如何消费**（均已接入）：
+
+| 门                        | 消费方式                                                                                                                                                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `verify:bg-clean`         | 仅检查 `role=background` 且 `usage=runtime` 的图；`reference-only`/非背景跳过；用 `roi.board` 覆盖默认棋盘区；bg 目录下未在 manifest 声明的图 = 失败                                                               |
+| `verify:text-overlap`     | `allowedText`（screen + per-asset 并集）从「文字过多」计数规则中扣除，杀掉合法 CTA 文案的误报；IoU 重叠规则不放宽（重叠永远是布局 bug）                                                                            |
+| `verify:tile-consistency` | 仅对 `role=tile` 且 `usage=runtime` 的瓦片做剪影一致性；`reference-only`/非 tile 跳过；tiles 目录下未声明的瓦片 = 失败                                                                                             |
+| `verify:visual`           | manifest 的 reference 资产（`usage=reference-only` 或 `role=reference`）构成 reference **白名单**，scene-aware（`selectedMcOption`）仍决定配哪一张；任何 runtime 资产被排除在 reference 之外（杜绝运行时产物自证） |
+
+manifest **可选且缺省兼容**：没有该文件时门按旧默认行为运行；一旦存在则必须通过 schema 校验与磁盘对账，否则消费它的门直接失败。
+
+---
+
+## layout.rules 规则类型
+
+| type          | 字段          | 含义                                                 |
+| ------------- | ------------- | ---------------------------------------------------- |
+| `safe_top`    | region, min   | region.y0 ≥ min（min 可为 `safeArea.minTop` 表达式） |
+| `min_gap`     | a, b, min     | region b 顶边 − region a 底边 ≥ min                  |
+| `inside_band` | region, band  | region 完全落在 band 的 y 范围内                     |
+| `ordered`     | first, second | first 底边 ≤ second 顶边（无重叠、顺序正确）         |
+
+### region 定义
+
+- 轴对齐矩形，y 向下
+- `y0` / `y1`：顶/底边表达式
+- `cy` / `h`：中心 y + 高度（自动换算 y0/y1）
+
+表达式解析：`scripts/lib/config_expr.js` — 白名单求值，禁止 `eval` 任意 JS。
+
+---
+
+## 检测脚本清单
+
+### 编排
+
+| 脚本                 | 说明                                                              |
+| -------------------- | ----------------------------------------------------------------- |
+| `scripts/run_all.py` | `--profile` / `--only assets\|layout\|all` / `--json report.json` |
+
+### 资源层（Python）
+
+| 脚本                           | 级别 | 检测内容                        |
+| ------------------------------ | ---- | ------------------------------- |
+| `verify_profile_schema.py`     | fail | Profile JSON Schema             |
+| `verify_assets_present.py`     | fail | standalone / source PNG 存在    |
+| `verify_asset_sizes.py`        | fail | PNG 尺寸 vs profile             |
+| `verify_atlas_frames.py`       | fail | atlas JSON 帧名、frame 尺寸     |
+| `verify_atlas_budget.py`       | fail | 各 sheet / 总量 vs thresholds   |
+| `verify_doc_asset_sync.py`     | warn | asset-naming.md 表格 vs profile |
+| `verify_fetch_antipatterns.py` | warn | placehold.co 引用               |
+
+### 布局层（Node）
+
+| 脚本                          | 级别      | 检测内容                                   |
+| ----------------------------- | --------- | ------------------------------------------ |
+| `verify_game_config_load.js`  | fail      | vm 加载 game-config，configKeys 为有限正数 |
+| `verify_layout_regions.js`    | fail      | 执行 layout.rules                          |
+| `verify_hardcoded_layout.js`  | warn/fail | antipatterns grep                          |
+| `verify_script_load_order.js` | fail      | index.html 含 loadOrder 子序列             |
+
+---
+
+## 故障对照表
+
+| 检测报告                         | 可能原因              | 修复                                               |
+| -------------------------------- | --------------------- | -------------------------------------------------- |
+| `safe_top` 失败                  | HUD 顶天              | 增大 `SAFE_TOP`，检查 `applySafeLayout`            |
+| `min_gap combo->cta` 失败        | 连击条压 CTA          | 增大 `COMBO_GAP_ABOVE_CTA` 或调整 COMBO_HUD_Y 推导 |
+| `inside_band combo` 失败         | 连击条跑到棋盘/CTA 外 | 检查 COMBO_HUD_Y 公式                              |
+| `verify_assets_present`          | PNG 缺失              | 跑 generate-ui / fetch-assets                      |
+| `verify_asset_sizes`             | 尺寸不符              | 按 profile 导出 PNG 或更新 profile                 |
+| `verify_atlas_frames`            | JSON 帧漂移           | `npm run build-atlas`                              |
+| `verify_doc_asset_sync` warn     | 文档过时              | 同步 `docs/asset-naming.md`                        |
+| `verify_fetch_antipatterns` warn | 仍用 placehold.co     | 改本地占位脚本                                     |
+| `verify_script_load_order`       | 脚本顺序错            | 调整 index.html（如 match-fx 在 match-system 前）  |
+| `hardcoded_cta_y` warn           | 魔数 CTA_Y            | 改走 applySafeLayout                               |
+
+---
+
+## 麻将示例 profile 典型值
+
+`examples/mahjong-match.profile.yaml` / 根目录 `playable.ui.profile.yaml`
+
+| Key             | 近似值 (SAFE_TOP=80) |
+| --------------- | -------------------- |
+| `HUD.BAR_Y`     | 80                   |
+| `PLAY_AREA_TOP` | ~176                 |
+| `CTA_Y`         | ~1776                |
+| `COMBO_HUD_Y`   | ~1690                |
+
+---
+
+## 可选 modules（文档标签）
+
+| module         | 说明                           | 本仓库 |
+| -------------- | ------------------------------ | ------ |
+| `boardBounds`  | 动态棋盘框 `getLayoutBounds()` | ✓      |
+| `hudChrome`    | 共享 HUD 绘制                  | ✓      |
+| `matchShatter` | 碰撞碎裂 VFX                   | ✓      |
+
+未启用模块时，profile 中设为 `false` 即可。
+
+---
+
+## 依赖
+
+```bash
+pip install pyyaml jsonschema pillow
+```
+
+Node 18+（内置 `vm`、`fs`）；profile 加载通过 python3 + pyyaml，无需 npm 包。
+
+---
+
+## 扩展检测
+
+1. 在 `scripts/` 添加新 verifier，输出 `--json` 格式 Report
+2. 注册到 `run_all.py` 的 `ASSET_CHECKS` 或 `LAYOUT_CHECKS`
+3. 若需新 rule type，扩展 `verify_layout_regions.js` 的 `checkRule` + schema enum
+
+**不要**在 verifier 中写死玩法逻辑 — 一切阈值与路径来自 profile。

package/project-template/skills/playable-verify-ui/references/phaser-patterns.md

@@ -0,0 +1,67 @@
+# Phaser Patterns
+
+## Uniform CTA (recommended default)
+
+```js
+// game-config.js
+CTA_NATIVE_W: 820,
+CTA_NATIVE_H: 190,
+CTA_SCALE: 0.61,
+CTA_TEXT_Y_RATIO: 81.5 / 190,
+
+// applySafeLayout
+cfg.CTA_FRAME_W = Math.round(cfg.CTA_NATIVE_W * cfg.CTA_SCALE);
+cfg.CTA_FRAME_H = Math.round(cfg.CTA_NATIVE_H * cfg.CTA_SCALE);
+cfg.CTA_TEXT_Y = cfg.CTA_Y + cfg.CTA_NATIVE_H * cfg.CTA_TEXT_Y_RATIO * cfg.CTA_SCALE;
+
+// CTAButton
+this.btn = ASSET_MANIFEST.addImage(scene, cx, cy, 'ui_cta_btn');
+this.btn.setScale(GAME_CONFIG.CTA_SCALE);
+```
+
+## HUD panel NineSlice
+
+```js
+ASSET_MANIFEST.addNineSlice(scene, cx, cy, 'ui_timer_panel', panelW, panelH);
+// UI_NINE_SLICE.ui_timer_panel: { left, right, top, bottom } in source px
+```
+
+## Content center helper
+
+```js
+const UiLayout = {
+  contentCenter(frameX, frameY, frameW, frameH, content) {
+    return {
+      x: frameX + content.left + (frameW - content.left - content.right) / 2,
+      y: frameY + content.top + (frameH - content.top - content.bottom) / 2,
+    };
+  },
+};
+```
+
+## Digit / dynamic text
+
+- Use `DigitDisplay` anchored at content center X
+- Shrink `DIGIT_HUD_W/H` when frame inner height < 60px
+- Do not place digits at `panelX + 252` magic offsets
+
+## Anti-patterns in this repo
+
+```js
+// BAD — deforms ornate CTA
+bg.setDisplaySize(500, 163);
+addNineSlice(..., 500, 163); // when source is 820×190
+
+// BAD — splits atlas frame
+left.setCrop(0, 0, capL, h);
+center.setCrop(capL, 0, midW, h);
+right.setCrop(nativeW - capR, 0, capR, h);
+
+// BAD — frame vs slot height mismatch
+cy = CTA_Y + CTA_H / 2; // when CTA_FRAME_H !== CTA_H
+```
+
+## Debug controls
+
+`SHOW_DEBUG_BUTTON: true` enables `DebugButton`（一键通关）in `debug-tools.js`.
+Set `false` before production builds.

package/project-template/skills/playable-verify-ui/references/scaling-decision-tree.md

@@ -0,0 +1,51 @@
+# Scaling Decision Tree
+
+## 1. Does the asset have fixed ornamental end caps?
+
+**Yes** (CTA 祥云耳、HUD 绳结、toast 金角)
+
+→ Ask: Must display width differ from source width?
+
+| Need narrower?               | Approach                                                              |
+| ---------------------------- | --------------------------------------------------------------------- |
+| Yes, no deformation          | **Uniform scale only** — accept smaller height too                    |
+| Yes, only middle may stretch | **NineSlice** with measured caps; keep display height ≈ source height |
+| No                           | `setScale(1)` or single uniform scale                                 |
+
+**Never**
+
+- `setDisplaySize(500, 163)` when source is `820×190`
+- NineSlice display size with `widthRatio ≠ heightRatio` on ornate caps
+- Three `setCrop` slices from one atlas frame
+
+## 2. Is the asset a flat horizontal bar?
+
+**Yes** (combo badge middle, simple progress strip)
+
+→ NineSlice or `setDisplaySize` with matched aspect is OK if caps are in slice borders.
+
+## 3. Text overlay
+
+Always layout in **content rect**, not frame rect:
+
+```
+contentX = frameX + left + (frameW - left - right) / 2
+contentY = frameY + top + (frameH - top - bottom) / 2
+```
+
+For asymmetric gold borders, measure `top` and `bottom` separately from PNG.
+
+## 4. Width feels too large after correct scaling
+
+| Option                       | Trade-off                                  |
+| ---------------------------- | ------------------------------------------ |
+| Lower `CTA_SCALE`            | Smaller button, correct proportions        |
+| Re-export squarer art        | Best visual, requires art pass             |
+| NineSlice narrow center only | Works for simple bars; risky on ornate CTA |
+
+## 5. Regression signals
+
+- End gems look like ovals → non-uniform scale
+- Gap between ears and red bar → broken crop / wrong slice
+- Text hugs top gold line → inset.top too small or bounds nudge missing
+- HUD ok, CTA bad → different rules; CTA prefers uniform scale

package/project-template/skills/playable-verify-ui/requirements.txt

@@ -0,0 +1,7 @@
+pyyaml>=6.0
+jsonschema>=4.0
+Pillow>=10.0
+# Optional: OCR for verify:text-overlap. Also needs the system `tesseract` binary
+# (brew install tesseract / apt-get install tesseract-ocr). Without it the
+# text-overlap gate reports DEGRADED (and fails under --strict).
+pytesseract>=0.3.10

package/project-template/skills/playable-verify-ui/schema/asset-manifest.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "asset-manifest.schema.json",
+  "title": "Playable asset-manifest",
+  "description": "结构化资产契约：声明每张图的 role / usage / roi / allowedText，供视觉门消费。key 必须是 numericId。",
+  "type": "object",
+  "required": ["assets"],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "assets": {
+      "type": "object",
+      "description": "以 numericId（纯数字）为 key 的资产表",
+      "patternProperties": {
+        "^[0-9]+$": { "$ref": "#/definitions/asset" }
+      },
+      "additionalProperties": false
+    },
+    "screen": {
+      "type": "object",
+      "properties": {
+        "allowedText": { "$ref": "#/definitions/allowedText" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "asset": {
+      "type": "object",
+      "required": ["path", "role"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "role": {
+          "type": "string",
+          "enum": [
+            "background",
+            "tile",
+            "cta",
+            "logo",
+            "decoration",
+            "character",
+            "prop",
+            "ui",
+            "fx",
+            "reference"
+          ]
+        },
+        "usage": { "type": "string", "enum": ["runtime", "reference-only"], "default": "runtime" },
+        "roi": {
+          "type": "object",
+          "description": "归一化 ROI，name -> [x1,y1,x2,y2]，取值 0..1 且 x1<x2,y1<y2",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "number", "minimum": 0, "maximum": 1 },
+            "minItems": 4,
+            "maxItems": 4
+          }
+        },
+        "allowedText": { "$ref": "#/definitions/allowedText" }
+      },
+      "additionalProperties": true
+    },
+    "allowedText": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/project-template/skills/playable-verify-ui/schema/playable-ui-profile.schema.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "playable-ui-profile.schema.json",
+  "title": "Playable UI Profile",
+  "type": "object",
+  "required": ["meta", "paths", "safeArea", "assets", "layout"],
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": ["engine", "design"],
+      "properties": {
+        "engine": { "type": "string", "enum": ["phaser3", "cocos", "pixi"] },
+        "name": { "type": "string" },
+        "design": {
+          "type": "object",
+          "required": ["width", "height"],
+          "properties": {
+            "width": { "type": "integer", "minimum": 1 },
+            "height": { "type": "integer", "minimum": 1 }
+          }
+        }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "required": ["gameConfig", "indexHtml", "assetsRoot", "atlasRoot"],
+      "properties": {
+        "gameConfig": { "type": "string" },
+        "indexHtml": { "type": "string" },
+        "assetsRoot": { "type": "string" },
+        "atlasRoot": { "type": "string" },
+        "assetNamingDoc": { "type": "string" },
+        "buildAtlasScript": { "type": "string" },
+        "fetchAssetsScript": { "type": "string" }
+      }
+    },
+    "safeArea": {
+      "type": "object",
+      "required": ["minTop", "minBottom", "minSide"],
+      "properties": {
+        "minTop": { "type": "number", "minimum": 0 },
+        "minBottom": { "type": "number", "minimum": 0 },
+        "minSide": { "type": "number", "minimum": 0 }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "required": ["standalone", "atlases"],
+      "properties": {
+        "standalone": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["key", "path", "width", "height"],
+            "properties": {
+              "key": { "type": "string" },
+              "path": { "type": "string" },
+              "width": { "type": "integer" },
+              "height": { "type": "integer" }
+            }
+          }
+        },
+        "atlases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "json", "png", "frames"],
+            "properties": {
+              "name": { "type": "string" },
+              "json": { "type": "string" },
+              "png": { "type": "string" },
+              "procedural": { "type": "boolean" },
+              "frames": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "width", "height"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "source": { "type": "string" },
+                    "width": { "type": "integer" },
+                    "height": { "type": "integer" },
+                    "procedural": { "type": "boolean" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "required": ["configKeys", "regions", "rules"],
+      "properties": {
+        "configKeys": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "regions": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "y0": { "type": "string" },
+              "y1": { "type": "string" },
+              "cy": { "type": "string" },
+              "h": { "type": "string" }
+            }
+          }
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["min_gap", "inside_band", "safe_top", "safe_bottom", "ordered"]
+              },
+              "a": { "type": "string" },
+              "b": { "type": "string" },
+              "region": { "type": "string" },
+              "band": { "type": "string" },
+              "min": { "type": ["number", "string"] },
+              "first": { "type": "string" },
+              "second": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "antipatterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "grep", "paths"],
+        "properties": {
+          "id": { "type": "string" },
+          "grep": { "type": "string" },
+          "paths": { "type": "array", "items": { "type": "string" } },
+          "exclude": { "type": "array", "items": { "type": "string" } },
+          "severity": { "type": "string", "enum": ["fail", "warn"] }
+        }
+      }
+    },
+    "scripts": {
+      "type": "object",
+      "properties": {
+        "loadOrder": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "thresholds": {
+      "type": "object",
+      "properties": {
+        "maxAtlasSheetKb": { "type": "number" },
+        "maxStandaloneKb": { "type": "number" },
+        "maxTotalAssetsMb": { "type": "number" }
+      }
+    },
+    "modules": {
+      "type": "object",
+      "additionalProperties": { "type": "boolean" }
+    }
+  }
+}