@playcraft/cli 0.0.44 → 0.0.47

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

@@ -0,0 +1,394 @@
+# Technical Artist Log
+
+## Upstream Intake
+
+> **Step 0a — mandatory before Skill Discovery or any generation.** Read each doc; one-line takeaway proves you understood upstream work. Game Designer/Artist keep **四件套** short — detail is in `style-exploration` + this project's `artist-log`.
+
+| Doc                         | Read ✓ | One-line takeaway (what matters for TA this round)      |
+| --------------------------- | ------ | ------------------------------------------------------- |
+| `docs/project-state.md`     | ☐      | {{e.g. Wave 1 done, selectedMcOption=B}}                |
+| `docs/design-brief.md`      | ☐      | {{e.g. Competence arc, match-3, Hook=wrong-move tease}} |
+| `docs/layout-spec.md`       | ☐      | {{e.g. 42 assetMapping rows, 3 atlas groups}}           |
+| `docs/atom-tree.json`       | ☐      | {{e.g. 18 TA atoms, C₁ refs artist-sample}}             |
+| `docs/atom-tree.md`         | ☐      | Reading guide + mediaGroups decisions                   |
+| `docs/style-exploration.md` | ☐      | {{e.g. MC path + storyboard EndCard tone}}              |
+| `logs/artist-log.md`        | ☐      | {{e.g. Palette Locked delta, Style Intent Notes}}       |
+
+```bash
+# Optional paste: ls assets/images/reference/ + key contract dirs after read
+{{intake_ls_snippet}}
+```
+
+---
+
+## Delivery Summary
+
+- **Assigned atoms**: {{total_assigned}}
+- **Completed**: {{total_completed}}
+- **Skipped**: {{total_skipped}}
+- **Blocked**: {{total_blocked}}
+- **Artist samples received**: {{artist_sample_count}} files
+- **TA-completed elements**: {{ta_completed_count}} files
+
+---
+
+## mediaGroups Reuse
+
+> **Step 0 Pre — mandatory before Skill Discovery.** Filter `atom-tree.json` → `meta.skillsMatch.mediaGroups` by `extension`; TA is responsible for **`.aiimage` + `.aisprite`** (Artist handles `.aiaudio`).
+
+| 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 / —}}            |
+
+<!--
+  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 — Artist owns them):
+    .aiaudio — BGM / SFX → see artist-log.md § mediaGroups Reuse
+
+  Filter command:
+    cat docs/atom-tree.json | jq '.meta.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.
+-->
+
+---
+
+## Skill Preflight
+
+> **Step 0 Part C — mandatory before production.** Read all relevant playcraft pipeline Skills.
+
+| Skill                       | 已读 | 关键决策摘要                                              |
+| --------------------------- | ---- | --------------------------------------------------------- |
+| playcraft-image-generation  | ☐    | {{model choice, reference-image strategy, background}}    |
+| playcraft-masking           | ☐    | {{floodfill tolerance, segment fallback, method-ai case}} |
+| playcraft-sprite-generation | ☐    | {{single-frame→merge workflow, batch threshold}}          |
+| playcraft-text-rendering    | ☐    | {{blue screen for text, stroke protection}}               |
+| playcraft-vfx-animation     | ☐    | {{per-frame generation, blue screen for VFX}}             |
+| playcraft-batch-pipeline    | ☐    | {{>5 elements → script, reference anchoring}}             |
+| playcraft-style-qa          | ☐    | {{dark-bg verify, MC consistency check}}                  |
+
+<!--
+  MUST be filled before Step 1 bulk generation. Each row: ✅ after reading + one-line decision summary.
+  Without this table → no bulk generation → no STOP.
+-->
+
+---
+
+## Style Interpretation
+
+> **Step 0c — Mandatory before any completion work.**
+> Read `logs/artist-log.md` Style Intent Notes, write your interpretation here.
+
+| #     | Artist Intent (Quote from artist-log.md) | My Interpretation     | Confidence      | Action            |
+| ----- | ---------------------------------------- | --------------------- | --------------- | ----------------- |
+| {{n}} | "{{artist_quote}}"                       | {{my_interpretation}} | high/medium/low | proceed / clarify |
+
+<!--
+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     → HOLD that asset type only: write question to docs/intent-clarifications.md
+           (routeTo: artist if style ambiguity; routeTo: game-designer if contract ambiguity)
+           → continue producing OTHER asset types where confidence ≥ medium
+           → resume the held type only after ICP answer (or Artist supplementary PNG per
+             artist-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
+
+> **Step 0d — mandatory before any asset generation.** Plan WHAT to produce, in WHAT order, using WHAT pipeline.
+
+### Coverage Plan
+
+| assetMapping id | Contract path             | Pipeline               | Reference source  | Priority        |
+| --------------- | ------------------------- | ---------------------- | ----------------- | --------------- |
+| {{elementId}}   | {{path from layout-spec}} | {{extract/generate/…}} | {{MC/ASR/sample}} | {{high/normal}} |
+
+<!--
+One row per layout-spec assetMapping entry. Row count must match assetMapping count (no gaps).
+-->
+
+### Atlas Assembly Plan
+
+| Atlas group | Output path (.webp + .json)     | Elements (frameIds)  | Layout       |
+| ----------- | ------------------------------- | -------------------- | ------------ |
+| {{tiles}}   | {{assets/images/tiles/…_atlas}} | {{tile_01..tile_06}} | {{3x2 grid}} |
+
+<!--
+Must match layout-spec § atlas grouping table.
+-->
+
+### Pipeline Order
+
+1. Extract: crop MC/ASR reference elements (Stage E)
+2. Complete: batch generate remaining elements (Stage A)
+3. Process: resize + format convert to WebP (Stage B)
+4. Assemble: build atlases with JSON sidecars (Stage C)
+5. Verify: Compliance Gate on all paths
+
+### Risk Checklist
+
+- [ ] Every assetMapping entry in Coverage Plan (no gaps)
+- [ ] Atlas groups match layout-spec grouping table
+- [ ] MC + ASR reference images accessible
+- [ ] Style Interpretation confidence ≥ medium for all asset types
+- [ ] Transparency Classification table complete (Step 0e below)
+
+**MUST NOT** start bulk generation until every Risk Checklist item is checked `[x]`.
+
+---
+
+## Transparency Classification
+
+> **Step 0e — mandatory before any generation.** TA auto-derives `needsAlpha` from path convention + `alphaStrategy` from element color palette and edge softness. See `ta-pipeline-cookbook.md` Step 0e and `skills/playable-art/references/alpha-postprocess.md` for full rules.
+
+| #     | assetMapping path | needsAlpha     | alphaStrategy                                      | Prompt strategy              | Postprocess tool                                      | Fallback                           | Dark-bg verify | 验证结果    |
+| ----- | ----------------- | -------------- | -------------------------------------------------- | ---------------------------- | ----------------------------------------------------- | ---------------------------------- | -------------- | ----------- |
+| {{n}} | {{path}}          | {{true/false}} | {{chroma / dual-bg-diff / rgb-alpha-split / black-add / opaque}} | {{green key / RGB+A / etc.}} | {{remove-bg / extract-alpha-split / dual-bg / N/A}} | {{rgb-alpha-split / black-add / N/A}} | {{clean / fail}} | {{✅ / ❓}} |
+
+<!--
+TA auto-derives transparency — does NOT depend on Game Designer fields.
+
+needsAlpha derivation (from assetMapping path):
+  images/bg/    → false (full-screen background)
+  images/ui/    → true  (UI overlay)
+  images/txt/   → true  (text image)
+  images/vfx/   → true  (VFX sprite)
+  images/tiles/ → true  (default; unless card/board rect body → false)
+
+alphaStrategy derivation:
+  Hard-edge UI/text/sprite    → chroma (choose green/blue/magenta by palette conflict)
+  Soft antialias/shadow       → rgb-alpha-split first; dual-bg-diff only when geometry is fixed
+  VFX glow/particle/ring      → black-add when ADD blend is acceptable; otherwise rgb-alpha-split
+  Full-screen background      → opaque
+
+chroma key color derivation:
+  Gold/yellow/orange/amber   → bluescreen (NEVER green — color bleed)
+  Green/teal/cyan            → bluescreen (NEVER green — same family)
+  Blue/indigo/purple         → greenscreen (NEVER blue — same family)
+  Multi-color/rainbow        → magenta (last resort)
+  Red/pink/white/black       → greenscreen or bluescreen (both safe)
+
+TA tool chain (must use, never skip):
+  1st: playcraft image remove-background --method floodfill --tolerance 25
+  2nd: python3 skills/playable-art/scripts/extract-alpha-split.py (RGB+A side-by-side)
+  3rd: python3 skills/playable-art/scripts/extract-dual-bg-alpha.py (matched dual backgrounds)
+  4th: playcraft image segment --boxes (complex edges, known position)
+  5th: playcraft image remove-background --method ai (hair/transparency)
+  6th: playcraft image segment --text (unknown position, last resort)
+  Extract: playcraft image crop (grid) or decompose-layers (multi-layer MC)
+
+Post-verify: overlay on #1A1A2E dark bg to check:
+  ✅ No white edges, no chroma residue, no black blocks, clean edges
+  ❌ If any issue → escalate through fallback tool chain
+-->
+
+**MUST NOT** proceed to Step 1 bulk generation if any row has `❓ pending` in 验证结果.
+
+### Video Alpha Classification
+
+| #     | video path | videoAlphaStrategy                                      | Matte source            | Validator evidence | Fallback             |
+| ----- | ---------- | ------------------------------------------------------- | ----------------------- | ------------------ | -------------------- |
+| {{n}} | {{path}}   | {{chroma-video / dual-bg-video / rgb-alpha-video / opaque-video}} | {{green / dual / alpha / n-a}} | {{MP4 timestamp + symptom}} | {{rerender / still sprite / n-a}} |
+
+<!--
+Video alpha is a production convention in this template, not a full codec pipeline.
+Validator feedback must still route symptoms:
+  green edge / matte spill → chroma-video key conflict
+  double subject / shimmer → dual-bg-video geometry drift
+  alpha timing mismatch → rgb-alpha-video matte alignment
+  black box around glow → use black-add still frames or VFX clean harness
+-->
+
+---
+
+## Style Reference
+
+- **Master reference (MC)**: `assets/images/storyboard/master_composite_option_{{selectedMcOption}}.png`
+- **ASR references**: `ui_state_sheet_{{selectedMcOption}}.png`, `element_state_sheet_{{selectedMcOption}}.png`
+- **Artist samples used as reference**: {{artist_sample_paths}}
+- **Reference model used**: `{{model_name}}` (must be `google/` native for style-consistent completions)
+
+---
+
+## Asset Completion Log
+
+> Records all elements derived from Artist samples.
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Completion type**: {{derived_from_sample | sprite_sheet | 3d_render | animation | vfx}}
+- **Source samples**: {{artist_sample_paths}}
+- **Elements completed**:
+  | File | Dimensions | Size | Notes |
+  |------|-----------|------|-------|
+  | {{path}} | {{WxH}} | {{size}} | {{notes}} |
+- **Pipeline**:
+  ```
+  {{step 1: e.g., generate-image --reference-image ...}}
+  {{step 2: e.g., image remove-background ...}}
+  {{step 3: e.g., image resize ...}}
+  ```
+- **Model used**: {{model_name}}
+- **Reference images**: {{reference_image_paths}}
+
+<!-- Repeat for each completion atom -->
+
+---
+
+## Technical Pipeline Log
+
+> Records all technical production work (sprite sheets, 3D, animation, VFX, post-processing).
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Pipeline type**: {{sprite_sheet | 3d_model | animation_frames | vfx | image_processing | audio_processing}}
+- **Input**: {{input_files}}
+- **Output**: {{output_files}}
+- **Commands executed**:
+  ```bash
+  {{command 1}}
+  {{command 2}}
+  ```
+- **Result**:
+  | File | Format | Dimensions | Size | Frame Count |
+  |------|--------|-----------|------|-------------|
+  | {{path}} | {{format}} | {{WxH}} | {{size}} | {{N or —}} |
+
+<!--
+For sprite_sheet / animation_frames / vfx pipeline types, fill the Sprite Grid Params section below.
+JSON is only auto-generated by `sprite-sheet` command. `animate` and `use-vfx` produce PNG only.
+-->
+
+- **Sprite Grid Params** _(animation_frames / vfx 必填；sprite_sheet 填"见 JSON")_:
+  - columns: {{N or "见 JSON"}}
+  - frameWidth: {{W}}px _(or "见 JSON")_
+  - frameHeight: {{H}}px _(or "见 JSON")_
+  - frameCount: {{N or "见 JSON"}}
+  - padding: {{0 or N}}px
+  - JSON available: {{yes — `<path>.json` (sprite-sheet) / no — params above are source of truth (animate/use-vfx)}}
+  - Dimensions verified: {{width = cols×frameW ✅ / ❌ mismatch}} | {{channels = 4 ✅ / ❌ no alpha}}
+
+<!-- Repeat for each pipeline atom -->
+
+---
+
+## Micro-Batch Validation
+
+> **Per asset type — first 2 completions must pass validation before continuing batch production.**
+> Compare each completion side-by-side with the Artist sample.
+
+### {{asset_type}} (e.g., tiles / ui / bg / vfx)
+
+| Batch | Files         | Consistency Score (1-5) | Deviation Items    | Adjustments Made |
+| ----- | ------------- | ----------------------- | ------------------ | ---------------- |
+| {{n}} | {{file_list}} | {{score}}               | {{deviation_list}} | {{adjustments}}  |
+
+<!--
+Consistency Score criteria:
+  5 — Perfect match: could be mistaken for original artist sample
+  4 — Good match: minor differences only visible on close inspection
+  3 — Acceptable match: style is recognizable but some attributes drift
+  2 — Poor match: obvious style deviation, needs significant adjustment
+  1 — Mismatch: completely different style, STOP and ask Artist
+
+Score < 3 → STOP this asset type, write question to docs/intent-clarifications.md
+-->
+
+---
+
+## Compliance Gate Results
+
+> Completed after Artist Ph.2 is confirmed done. Verify all assetMapping entries.
+
+### Asset Coverage Check
+
+| assetMapping Entry | Expected Path        | File Exists? | Dimensions | Size     | Status        |
+| ------------------ | -------------------- | ------------ | ---------- | -------- | ------------- |
+| {{elementId}}      | {{visualAsset_path}} | {{Yes/No}}   | {{WxH}}    | {{size}} | {{PASS/FAIL}} |
+
+<!--
+Fill one row per entry in layout-spec.md assetMapping.
+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}} |
+| **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
+
+| Check                        | Target                                             | Actual     | Result        |
+| ---------------------------- | -------------------------------------------------- | ---------- | ------------- |
+| Classification table         | All rows filled, no ❓ pending                     | {{status}} | {{PASS/FAIL}} |
+| Alpha channels (transparent) | All transparent assets channels=4                  | {{count}}  | {{PASS/FAIL}} |
+| Dark-bg verify (transparent) | All transparent assets clean on #1A1A2E overlay    | {{count}}  | {{PASS/FAIL}} |
+| Alpha strategy recorded      | Every transparent asset has alphaStrategy + fallback | {{status}} | {{PASS/FAIL}} |
+| Video alpha strategy         | Every video asset has videoAlphaStrategy or opaque-video | {{status}} | {{PASS/FAIL}} |
+| BG full-coverage             | All backgrounds edge-to-edge, no fade/white corner | {{status}} | {{PASS/FAIL}} |
+| Atlas per-frame verify       | VFX/atlas each frame verified on dark bg           | {{status}} | {{PASS/FAIL}} |
+| Chroma residue               | Zero color residue from chroma key removal         | {{status}} | {{PASS/FAIL}} |
+
+### Compliance Verdict
+
+- **Overall**: {{PASS / FAIL}}
+- **Blockers** (if any): {{list of FAIL items that block integration}}
+- **Ready for Reviewer ui_diff**: {{Yes / No — pending fixes}}
+
+---
+
+## Handoff to Developer
+
+Summary of what TA delivers to Developer:
+
+| Asset Type          | Count | Paths                  | Notes                 |
+| ------------------- | ----- | ---------------------- | --------------------- |
+| Background images   | {{N}} | `assets/images/bg/`    | {{notes}}             |
+| Tile/element images | {{N}} | `assets/images/tiles/` | {{notes}}             |
+| UI elements         | {{N}} | `assets/images/ui/`    | {{notes}}             |
+| Sprite sheet atlas  | {{N}} | `assets/images/*/`     | Each has paired .json |
+| Animation frames    | {{N}} | `assets/images/*/`     | {{notes}}             |
+| VFX sprite sheets   | {{N}} | `assets/images/vfx/`   | {{notes}}             |
+| 3D GLB models       | {{N}} | `assets/models/`       | {{notes}}             |
+| BGM audio           | {{N}} | `assets/audio/bgm/`    | {{notes}}             |
+| SFX audio           | {{N}} | `assets/audio/sfx/`    | {{notes}}             |
+
+**All files path-match `layout-spec.md` assetMapping**: {{Yes / No}}
+
+<!--
+If No, list discrepancies here so Developer knows to use alternate paths.
+-->

package/project-templates/threejs/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["node"],
+    "paths": {
+      "assets/*": ["./assets/*"]
+    }
+  },
+  "include": ["main.ts", "game/**/*.ts", "globals.d.ts", "vite.config.ts"]
+}

package/project-templates/threejs/vite.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "vite";
+import path from "path";
+
+export default defineConfig(({ command }) => ({
+  define: {
+    __DEV__: JSON.stringify(command === "serve"),
+  },
+  resolve: {
+    alias: {
+      assets: path.resolve(__dirname, "assets"),
+    },
+  },
+  server: {
+    host: "0.0.0.0",
+    // Preferred port; strictPort:false (the default, set explicitly here for
+    // intent) lets Vite auto-increment when 3000 is taken. The harness scripts
+    // (dev:start / verify:* / record:mp4) parse Vite's actual "Local:" URL, so
+    // port drift never needs to be tracked by hand. See dev-start.mjs.
+    port: 3000,
+    strictPort: false,
+    open: true,
+  },
+  build: {
+    outDir: "dist",
+    sourcemap: true,
+  },
+}));