@playcraft/cli 0.0.42 → 0.0.43

package/project-template/templates/designer-log.template.md

@@ -48,19 +48,67 @@ Repeat this section for each atom.
 Fill in details as you complete each one.
 -->
 
+## Image Production Preflight (Phase 1 — Gate #2b)
+
+> **Mandatory before MC/ASR generation and before `#2b` STOP.** Read all three Skills; record key decisions.
+
+| Skill / Check               | 已读 | 关键决策摘要                                             |
+| --------------------------- | ---- | -------------------------------------------------------- |
+| playcraft-storyboard        | ☐    | MC 45:16 · model whitelist · Panel 1 all element types   |
+| playcraft-asset-state-sheet | ☐    | ASR grid · isolated cells · sheet #808080 · cell chroma  |
+| playcraft-image-generation  | ☐    | §3 chroma matrix · §3.1 ASR branch · no remove-bg on ASR |
+
+<!--
+  MUST be filled before generating ASR (Step 4) and before Gate #2b STOP.
+  Hook validate-workflow-stop enforces this section in style_exploration stage.
+-->
+
 ## ASR Coverage Matrix (designer-handoff-v2 — 100% contract rows)
 
 > UI: `assets/images/reference/ui_state_sheet_{{option}}.png`  
 > Element: `assets/images/reference/element_state_sheet_{{option}}.png`
 
-| Contract id                      | Type   | ASR sheet    | Grid (row,col) | State(s)    | TA extends? |
-| -------------------------------- | ------ | ------------ | -------------- | ----------- | ----------- |
-| {{element_id_from_assetMapping}} | visual | ui / element | {{1,1}}        | {{default}} | {{yes/no}}  |
-| {{static_text_id}}               | text   | ui / MC-crop | —              | baked       | {{yes/no}}  |
+### Sheet grid metadata (供 TA crop 计算)
+
+| Sheet                                  | Total rows    | Total cols | Cell W×H (px) | Cell padding (px) | Origin            |
+| -------------------------------------- | ------------- | ---------- | ------------- | ----------------- | ----------------- |
+| `ui_state_sheet_{{option}}.png`        | 2             | 4          | 800×800       | 80                | top-left (R1, C1) |
+| `element_state_sheet_{{option}}.png`   | 2             | 4          | 800×800       | 80                | top-left (R1, C1) |
+| `element_state_sheet_{{option}}_2.png` | (if overflow) |            |               |                   |                   |
+
+<!--
+Grid coordinates use 1-based indexing, row-major.
+Cell W×H = visible cell area (without padding). Padding = margin between cells AND outer margin.
+Pixel coordinates of cell (R, C):
+  x = (C - 1) × (cellW + padding) + padding
+  y = (R - 1) × (cellH + padding) + padding
+TA uses these for `playcraft image crop --x ... --y ... --width cellW --height cellH`.
+-->
+
+### Coverage
+
+| Contract id                      | elementType | Type   | CoverageLayer                 | ASR sheet    | Grid (row,col) | State(s)    | TA extends? |
+| -------------------------------- | ----------- | ------ | ----------------------------- | ------------ | -------------- | ----------- | ----------- |
+| {{element_id_from_assetMapping}} | {{type}}    | visual | on-asr / mc-crop / ta-extends | ui / element | {{R1C1}}       | {{default}} | {{yes/no}}  |
+| {{static_text_id}}               | —           | text   | mc-crop or on-asr             | ui / MC-crop | —              | baked       | {{yes/no}}  |
 
 <!--
 One row per layout-spec assetMapping elementId and per static text id.
-TA crop index + Phase 2 VisualAtom actualOutput: ASR:sheet:R#C#
+CoverageLayer:
+  on-asr     — physical slot on ASR PNG; Grid required; mirror atoms[].asrSlot
+  mc-crop    — MC Panel 1 only; ASR sheet = MC-crop
+  ta-extends — variant/extra states; TA extends? = yes + Style Intent note
+
+Type rule: each distinct elementType must have ≥1 row with on-asr OR mc-crop.
+Grid syntax: R{row}C{col}, e.g. R1C2, 1-based, row-major.
+TA crop + Phase 2 VisualAtom actualOutput: ASR:<sheet>:R#C#
+
+After filling this table, MIRROR each visual row into atom-plan.json:
+  atoms[].asrSlot = { "sheet": "ui" | "element", "row": <n>, "col": <n> }
+
+This lets TA batch-crop from atom-plan.json directly (see ta-pipeline-cookbook.md
+§ ASR 提取方法 "优先路径") instead of manually re-reading this Coverage table.
+See docs/team/atom-plan-format.md § `asrSlot` for full schema + crop formula.
 -->
 
 ## Palette Locked (from MC option {{option}})
@@ -90,6 +138,31 @@ TA crop index + Phase 2 VisualAtom actualOutput: ASR:sheet:R#C#
   mediaGroups: list each .aiaudio match disposition (linked/skipped + reason).
 -->
 
+## mediaGroups Reuse (Phase 2)
+
+> **Mandatory before any audio generation.** Filter `atom-plan.json` → `skillsMatch.mediaGroups` by `extension`; Designer is responsible for **`.aiaudio` only** (TA handles `.aiimage` / `.aisprite`).
+
+| mediaGroup atomId | extension | Matches Designer atom? | Disposition   | Reason (if skipped)                | Output path (if linked) |
+| ----------------- | --------- | ---------------------- | ------------- | ---------------------------------- | ----------------------- |
+| {{mg_atomId}}     | .aiaudio  | {{atom_id / —}}        | linked / skip | {{mood mismatch / wrong loop / —}} | {{path / —}}            |
+
+<!--
+  Designer scope (this table):
+    .aiaudio — BGM / SFX bundles → link or skip (with reason)
+
+  Out of Designer scope (do NOT fill rows for these — TA owns them):
+    .aiimage  — single-shot image atoms
+    .aisprite — sprite-sheet atoms (multi-frame)
+    .aigameplay / .aiconfig — Developer reads via skillRef
+
+  Filter command:
+    cat docs/atom-plan.json | jq '.skillsMatch.mediaGroups[] | select(.extension == ".aiaudio")'
+
+  Disposition rules:
+    linked → playcraft skills link → verify mood matches MC → status: done
+    skip   → quality / mood / loop mismatch → document reason → generate from scratch
+-->
+
 ## Style Consistency Self-Check
 
 - [ ] All visual assets share the same art style?

package/project-template/templates/layout-spec.template.md

@@ -82,6 +82,24 @@ Single large assets (full-screen bg) → one webp path only. Digit strip → sep
 Each elementId in assetMapping uses atlasPath + frameId OR single visualAsset path.
 -->
 
+Single-element groups stay as single-file paths; do not invent atlases for one texture.
+
+---
+
+## Element Type Registry (ASR capacity budget)
+
+Group `assetMapping` elementIds by **visual type** before Gate #1 lock. Designer needs **one representative per type** on ASR or MC Panel 1; color variants are `ta-extends`.
+
+| typeId   | elementIds (variants)        | Notes                           |
+| -------- | ---------------------------- | ------------------------------- |
+| {{type}} | {{id_a}}, {{id_b}}, {{id_c}} | e.g. tile colors share one type |
+
+**Budget**: aim for **≤ 20 unique types** and **≤ ~24 ASR physical slots** (ui board ~12 + element board ~12). If types > 12, plan `element_state_sheet_[X]_2.png` or extra `mc-crop` + `ta-extends` rows.
+
+Designer Coverage Matrix **elementType** column should match `typeId` here.
+
+---
+
 ## Asset Mapping
 
 | elementId      | visualAsset / atlas                   | frameId | sfx                                   |
@@ -131,16 +149,38 @@ TA extracts each text element using segment and saves to the specified path.
 
 ### Digit Sprite Strip (for dynamic numbers)
 
-- **Characters**: `{{digit_characters}}`
+- **Characters**: `{{digit_characters}}` _(typical "0123456789" — frameCount = 10)_
 - **Cell size**: {{cell_w}}x{{cell_h}}
-- **Asset path**: `assets/images/ui/digits.webp`
+- **Asset path**: `assets/images/txt/digits.webp` _(recommended: text-class lives under `images/txt/` per Transparency Classification)_
+- **Sidecar path (optional)**: `assets/images/txt/digits.json` _(only when laid out as multi-row grid; single-row strip can omit)_
+- **Layout**: single-row horizontal strip (default) — total width = `cell_w × frameCount`, height = `cell_h`
+- **Alpha**: required (channels = 4); TA uses **bluescreen** chroma (text typically gold/white — avoid green key)
 
 <!--
 PM defines the character set based on what dynamic text the game needs.
-Common sets:
-- Score only: "0123456789"
-- Score + timer: "0123456789:."
-- Score + multiplier: "0123456789x+,."
-Designer generates a single horizontal strip image with all characters in order.
-Developer slices by character index at runtime (char_x = index * cell_w).
+
+Common sets (always include digits 0–9 first, then any symbols):
+- Score only:         "0123456789"                 (frameCount = 10)
+- Score + timer:      "0123456789:."               (frameCount = 12)
+- Score + multiplier: "0123456789x+,."             (frameCount = 14)
+
+Path convention (TA Transparency Classification + Compliance Gate):
+- `assets/images/txt/digits.webp`   — preferred (text class → bluescreen, channels=4)
+- `assets/images/txt/digits_{{label}}.webp` — when multiple digit styles exist (score / countdown / level)
+- Legacy `assets/images/ui/digits.webp` works but TA must still classify it as text (bluescreen, not greenscreen).
+
+Layout (default single horizontal row):
+- Total width  = cell_w × frameCount
+- Total height = cell_h
+- Cell origin (0-based, row-major): x = index × cell_w, y = 0
+- Developer slices at runtime: char_x = index × cell_w
+
+Multi-row digit grid (rare — e.g. small + large digits in one sheet) MUST supply a `.json` sidecar
+describing each frame; Compliance Gate then checks dimensions against that sidecar.
+
+Compliance Gate (TA verifies before STOP):
+- frameCount = character count above
+- total width × height matches the layout (single-row or sidecar)
+- channels = 4 (alpha)
+- dark-bg verify: no chroma residue around digit edges
 -->

package/project-template/templates/ta-log.template.md

@@ -34,16 +34,27 @@
 
 ## mediaGroups Reuse
 
-> **Step 0 Pre — mandatory before Skill Discovery.** Check `atom-plan.json` → `skillsMatch.mediaGroups` for pre-matched reusable assets.
+> **Step 0 Pre — mandatory before Skill Discovery.** Filter `atom-plan.json` → `skillsMatch.mediaGroups` by `extension`; TA is responsible for **`.aiimage` + `.aisprite`** (Designer handles `.aiaudio`).
 
-| mediaGroup atomId | Matches TA atom? | Disposition   | Reason (if skipped)      | Output path (if linked) |
-| ----------------- | ---------------- | ------------- | ------------------------ | ----------------------- |
-| {{mg_atomId}}     | {{atom_id / —}}  | linked / skip | {{style mismatch / N/A}} | {{path / —}}            |
+| mediaGroup atomId | extension          | Matches TA atom? | Disposition   | Reason (if skipped)             | Output path (if linked) |
+| ----------------- | ------------------ | ---------------- | ------------- | ------------------------------- | ----------------------- |
+| {{mg_atomId}}     | .aiimage/.aisprite | {{atom_id / —}}  | linked / skip | {{style mismatch / wrong dims}} | {{path / —}}            |
 
 <!--
-  For each mediaGroup entry:
-    - "linked" = used the pre-matched asset → playcraft skills link → post-process → status=done
-    - "skip" = quality/style mismatch → document reason → generate from scratch
+  TA scope (this table):
+    .aiimage  — single-shot image bundles (bg, single ui element, single tile)
+    .aisprite — sprite-sheet bundles (multi-frame: tile sets, vfx, animations)
+
+  Out of TA scope (do NOT fill rows for these — Designer owns them):
+    .aiaudio — BGM / SFX → see designer-log.md § mediaGroups Reuse
+
+  Filter command:
+    cat docs/atom-plan.json | jq '.skillsMatch.mediaGroups[] | select(.extension == ".aiimage" or .extension == ".aisprite")'
+
+  Disposition rules:
+    linked → playcraft skills link → post-process (resize/convert/transparency) → status=done
+    skip   → quality / style / wrong dimensions → document reason → generate from scratch
+
   This section MUST be filled before proceeding to Step 0 Skill Discovery.
 -->
 
@@ -80,12 +91,17 @@
 | {{n}} | "{{designer_quote}}"                         | {{my_interpretation}} | high/medium/low | proceed / clarify |
 
 <!--
-Confidence rules:
+Confidence rules (atom-granularity — hold only the affected asset type, not the whole Wave 2):
   high    → proceed with completion
   medium  → proceed, but include style interpretation in --reference-image prompt
-  low     → MUST write question to docs/intent-clarifications.md before proceeding
-
-Do NOT proceed with any asset type where confidence = low.
+  low     → HOLD that asset type only: write question to docs/intent-clarifications.md
+           (routeTo: designer if style ambiguity; routeTo: pm if contract ambiguity)
+           → continue producing OTHER asset types where confidence ≥ medium
+           → resume the held type only after ICP answer (or Designer supplementary PNG per
+             designer-deliverable-spec.md § "ICP supplementary PNG — when (and only when)")
+
+You may STOP only when EVERY remaining asset type is held at confidence=low — otherwise keep
+making progress on the producible ones in parallel with the ICP wait.
 -->
 
 ## Production Plan
@@ -289,17 +305,29 @@ Every row must be PASS before advancing to integration.
 
 ### Spec Compliance Summary
 
-| Check                    | Target                     | Actual     | Result        |
-| ------------------------ | -------------------------- | ---------- | ------------- |
-| Background dimensions    | {{assetSpec}}              | {{actual}} | {{PASS/FAIL}} |
-| Tile dimensions          | {{assetSpec}}              | {{actual}} | {{PASS/FAIL}} |
-| UI element dimensions    | {{assetSpec}}              | {{actual}} | {{PASS/FAIL}} |
-| Background file size     | < 500KB                    | {{actual}} | {{PASS/FAIL}} |
-| Tile file size           | < 100KB per tile           | {{actual}} | {{PASS/FAIL}} |
-| BGM file size            | < 300KB                    | {{actual}} | {{PASS/FAIL}} |
-| SFX file size            | < 50KB per SFX             | {{actual}} | {{PASS/FAIL}} |
-| Total assets size        | ≤ 2-3MB                    | {{actual}} | {{PASS/FAIL}} |
-| Sprite sheet JSON paired | Every .png sheet has .json | {{yes/no}} | {{PASS/FAIL}} |
+| Check                      | Target                                                     | Actual     | Result        |
+| -------------------------- | ---------------------------------------------------------- | ---------- | ------------- |
+| Background dimensions      | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| Tile dimensions            | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| UI element dimensions      | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| **Text dimensions**        | `images/txt/*` per `layout-spec` text spec (W×H per label) | {{actual}} | {{PASS/FAIL}} |
+| **Digit Strip dimensions** | `images/txt/digits*` cellW × cellH × frameCount (0–9 = 10) | {{actual}} | {{PASS/FAIL}} |
+| Background file size       | < 500KB                                                    | {{actual}} | {{PASS/FAIL}} |
+| Tile file size             | < 100KB per tile                                           | {{actual}} | {{PASS/FAIL}} |
+| BGM file size              | < 300KB                                                    | {{actual}} | {{PASS/FAIL}} |
+| SFX file size              | < 50KB per SFX                                             | {{actual}} | {{PASS/FAIL}} |
+| Total assets size          | ≤ 2-3MB                                                    | {{actual}} | {{PASS/FAIL}} |
+| Sprite sheet JSON paired   | Every .png sheet has .json                                 | {{yes/no}} | {{PASS/FAIL}} |
+
+<!--
+  Text dimensions: every `images/txt/*` asset must match per-label W×H from layout-spec § Static text (or atlas grouping for text atlas).
+  Digit Strip dimensions: digit sprite (typically `images/txt/digits.webp` or `images/ui/digits.webp`) must satisfy:
+    - frameCount = 10 (0–9) — for score / countdown / level display
+    - width  == cellW × frameCount (when laid out as a single row)
+    - height == cellH (single-row strip)  OR  width × height matches multi-row grid in JSON sidecar
+    - channels = 4 (alpha for overlay)
+  If digit strip is split across multiple paths (e.g. small + large) each needs its own row.
+-->
 
 ### Transparency Compliance