@playcraft/cli 0.1.27 → 0.1.29

package/project-template-v2/.claude/agents/refs/developer-impl-cookbook.md

@@ -1,432 +0,0 @@
-# Developer Implementation Cookbook
-
-> Pattern reference for implementation decisions. Jump to the relevant section when you encounter that problem. Does not define when Developer runs, what Developer owns, or how STOP/handoff works.
-
-| Section                    | Jump to when                                               |
-| -------------------------- | ---------------------------------------------------------- |
-| Asset Placeholder Strategy | Phase 1 — every assetMapping entry needs a file on disk    |
-| Atlas binding              | Any element backed by `atlasPath + frameId` in layout-spec |
-| index.html Skeleton        | Setting up the entry point                                 |
-| PGS Implementation         | Implementing gameplay rules                                |
-| Scene module split         | Any `game/scenes/*.ts` approaching 350 lines               |
-
-Skill atoms with `skillRef` are intentionally not covered here — load skillRef or read the linked SKILL.md directly from `.claude/skills/<skillRef>/SKILL.md` (skills are already linked by plan stage). The Skills contain the authoritative recipe, binding pattern, and constraints for that atom. If a skill is not yet linked, load `playcraft-skill-recommender` for CLI reference.
-
-## Scene module split (hard constraint)
-
-- **`game/scenes/*.ts` must stay ≤ 350 lines** — split logic into `game/gameplay/` and constants into `game/config/` before the scene file grows
-- Use **Write / Edit per module** — never concatenate with `cat >` / `cat >>` heredoc (each append costs a full model turn)
-- If Write fails with `InputValidationError`, **split the file** — do not fall back to Bash heredoc
-
-## Asset Placeholder Strategy (Phase 1)
-
-> **Core rule**: Developer's job in the `build` loop is **playability + correct wiring**, not art. Visual presentation is explicitly out of scope until ring 4. Wire contract paths, batch-generate placeholder images where files are expected, and only code-draw when a static file truly cannot substitute. `playcraft skills link --from-atom-tree --prune` may already have placed Tier 1 assets on disk before Developer enters.
-
-### Develop-stage success criteria (not visual quality)
-
-| In scope (must pass)                                                       | Out of scope (defer)                     |
-| -------------------------------------------------------------------------- | ---------------------------------------- |
-| Core loop operable (input → response → state change)                       | Color harmony, style match, juice polish |
-| First-level win path reachable                                             | ASR / MC visual fidelity                 |
-| All contract image paths resolve (Tier 1/2) or documented Tier 3 exception | AI-generated or hand-drawn art           |
-| `npm run dev` — no 404s, no white-screen blockers                          | Audio playback (event hooks only)        |
-| CTA / scene flow wired per ring DoD                                        | Atlas production quality                 |
-
-### Three-tier decision tree
-
-For **every visual resource** expected by the current ring slice — `assetMapping`, gameplay entities, basic UI, CTA, necessary VFX — apply in order:
-
-```
-File already exists at contract path (linked by ref-flow or scaffold)?
-  YES → confirm with playcraft image info; read atom's SKILL.md + ref/ source  (Tier 1)
-
-Contract path expects a static image file (tile, btn, bg, icon, vfx sprite)?
-  YES → npm run placeholder:gen to that exact path                      (Tier 2)
-        Do NOT code-draw a colored rect/circle instead of the file
-
-Static image file is NOT viable (dynamic digits, live counter, no contract path)?
-  YES → minimal code-draw (fillText / Graphics / DOM text)              (Tier 3)
-        Document reason in developer-log § Placeholder materialization
-
-NEVER: playcraft image generate, AI image tools, hand-drawn art, or visual polish time
-```
-
-#### Tier 1 — file already at contract path
-
-The ref-flow subagent runs `playcraft skills link --from-atom-tree --prune` before Developer enters. If a mediaGroups match existed, the asset is already on disk. Developer's job is to **understand how to use it**:
-
-```bash
-# Confirm the file exists and get its dimensions
-playcraft image info <contract-path>
-
-# Read the skill to understand binding pattern and API
-# Skills are already linked under .claude/skills/<skillRef>/ — read locally:
-#   SKILL.md → ref/ → source code (in that order)
-```
-
-**Then read ref/ source** — SKILL.md documents the intent; ref/ source is the binding authority. Check constructor params, method signatures, event names, and frame keys from the actual code. When SKILL.md and source diverge, source wins.
-
-#### Tier 2 — local placeholder generator (fallback for unmatched visuals)
-
-When no mediaGroups match exists, generate a placeholder to the **exact contract path** during project assembly. Do not use inline URLs in code — the file must exist at the path so the code loads identically once TA delivers the real asset.
-
-The harness ships a **local** generator (`skills/_shared/scripts/gen-placeholder.py`) — offline, faster than placehold.co, and supports **shapes** (`fill`, `rounded`, `circle`, `ellipse`, `diamond`, `ring`, `triangle-*`). Use `shape: auto` to infer from `elementId` (e.g. `btn_*` → rounded, `tile_*` → circle).
-
-Maintain a batch placeholder script, normally `ta-workspace/scripts/gen-placeholders.mjs`, with one `PLACEHOLDERS` row for every missing visual resource expected by the minimal prototype. Copy from `templates/gen-placeholders.template.mjs`. Run before feature logic implementation so coding never depends on remote images.
-
-**Single file:**
-
-```bash
-npm run placeholder:gen -- \
-  -o assets/images/bg/bg_main.webp \
-  --size 750x1334 --bg 1a1a2e --fg cccccc \
-  --text bg_main --shape fill
-```
-
-**Batch script** — write this as `ta-workspace/scripts/gen-placeholders.mjs` and run once:
-
-```bash
-cp templates/gen-placeholders.template.mjs ta-workspace/scripts/gen-placeholders.mjs
-# edit PLACEHOLDERS rows, then:
-node ta-workspace/scripts/gen-placeholders.mjs
-# or: npm run placeholder:gen
-```
-
-```js
-// ta-workspace/scripts/gen-placeholders.mjs
-// Generate placeholder images at exact assetMapping contract paths.
-// Run: node ta-workspace/scripts/gen-placeholders.mjs
-// Uses local gen-placeholder.py — no network, supports shapes.
-
-import { spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-
-const ROOT = process.cwd();
-const GEN_SCRIPT = join(ROOT, 'skills/_shared/scripts/gen-placeholder.py');
-const BATCH_JSON = join(ROOT, 'ta-workspace/tmp/placeholders.batch.json');
-
-const PLACEHOLDERS = [
-  // { path, size, bg, fg, label, shape? }
-  {
-    path: 'assets/images/bg/bg_main.webp',
-    size: '750x1334',
-    bg: '1a1a2e',
-    fg: 'cccccc',
-    label: 'bg_main',
-    shape: 'fill',
-  },
-  {
-    path: 'assets/images/ui/btn_cta.webp',
-    size: '300x100',
-    bg: 'ff6b35',
-    fg: 'ffffff',
-    label: 'btn_cta',
-    shape: 'rounded',
-  },
-  {
-    path: 'assets/images/tiles/tile_gold.webp',
-    size: '128x128',
-    bg: 'ffcc00',
-    fg: '000000',
-    label: 'tile_gold',
-    shape: 'circle',
-  },
-  {
-    path: 'assets/images/tiles/tile_empty.webp',
-    size: '128x128',
-    bg: '333333',
-    fg: '888888',
-    label: 'tile_empty',
-    shape: 'circle',
-  },
-];
-
-mkdirSync(dirname(BATCH_JSON), { recursive: true });
-writeFileSync(BATCH_JSON, `${JSON.stringify(PLACEHOLDERS, null, 2)}\n`, 'utf8');
-spawnSync('python3', [GEN_SCRIPT, '--batch', BATCH_JSON], { cwd: ROOT, stdio: 'inherit' });
-```
-
-**CLI quick reference:**
-
-| Parameter    | Format                          | Example                                                                              |
-| ------------ | ------------------------------- | ------------------------------------------------------------------------------------ |
-| Size         | `{W}x{H}` (px)                  | `750x1334`                                                                           |
-| Square       | `{W}`                           | `128`                                                                                |
-| Background   | hex/CSS name, or gradient       | `1a1a2e`, `linear:ffcc00→ff9900:horizontal`, `radial:ff6b35@center→transparent@edge` |
-| Foreground   | same                            | `ffffff`                                                                             |
-| Format       | from `-o` extension             | `.webp` (match contract)                                                             |
-| Label        | `--text`                        | `--text tile_gold`                                                                   |
-| Role         | `--role` or row `role`          | `CTA button · 主按钮`（可选，默认从 elementId 推断）                                 |
-| Shape        | `--shape` or row `shape`        | `circle`, `rounded`, `auto`                                                          |
-| Transparency | default auto                    | non-`fill` shapes → **transparent outside silhouette**; `fill` → opaque full bleed   |
-| Override     | `--transparent` / `--opaque`    | force either behavior                                                                |
-| Retina       | `--retina 2` or row `retina: 2` | doubles WxH                                                                          |
-| Batch        | `--batch path.json`             | array of rows above                                                                  |
-| Sidecar      | auto `*.json` beside image      | same stem as output file; not loaded by game code                                    |
-
-**Sidecar JSON example** (`tile_gold.json` next to `tile_gold.webp`):
-
-```json
-{
-  "kind": "playcraft.placeholder",
-  "version": 1,
-  "label": "tile_gold",
-  "role": "tile · 方块",
-  "size": { "width": 128, "height": 128 },
-  "colors": { "bg": "#ffcc00", "fg": "#000000" },
-  "shape": "circle",
-  "transparent": true,
-  "format": "webp",
-  "image": "tile_gold.webp"
-}
-```
-
-**Three rules for placeholders:**
-
-1. **Size = contract size** — use exact dimensions from `layout-spec.md` → `assetMapping` → `spec`
-2. **Color = palette hint** — use the closest hex from `layout-spec.md` → `palette` so layout is legible
-3. **Label = elementId** — makes screenshots self-documenting during review
-
-**⚠️ Placeholder style constraints:**
-
-4. **No borders** — flat fill or shape silhouette only; no decorative stroke/frame around the image
-5. **One file per asset, no sprite sheets** — generate each asset as its own individual file. Do not pack multiple elements into a single image. Even if the final contract calls for an atlas, the Phase 1 placeholder for each `frameId` should be a separate file at its own path.
-6. **Metadata on image** — every placeholder shows **elementId**, **WxH**, **bg/fg hex**, and **role (作用)** so TA can replace without opening layout-spec. Optional `role` field overrides auto-inference (`btn_*` → `button · 按钮`).
-7. **Default WebP + sidecar JSON** — output format defaults to `.webp`. Each generated image gets a same-stem `.json` sidecar beside it (e.g. `tile_gold.webp` + `tile_gold.json`) with label, size, colors, shape, role, and transparency for TA handoff. Game code loads only the image path; the JSON is documentation, not runtime input.
-8. **Gradients + alpha fades** — `--bg` accepts `linear:` / `radial:` specs with `→` (or `->`) between stops. Stops support 8-digit hex alpha (`ffcc0080`) or `transparent`. Example: `--bg radial:ff6b35@center→transparent@edge --shape circle` for a soft glow placeholder.
-
-**Do not use placehold.co in project scripts** — `verify:ui` warns on `placehold.co` references. Use the local generator instead.
-
-#### Tier 3 — code-draw fallback (only when placeholder file is not viable)
-
-Use **only** when Tier 2 cannot apply — the resource is inherently dynamic or has no image contract path:
-
-| Resource                  | Tier 3 approach               | Notes                                                        |
-| ------------------------- | ----------------------------- | ------------------------------------------------------------ | ------------------- |
-| Digit strip / score font  | `ctx.fillText()` or `<span>`  | TA later drops WebP at contract path — code path unchanged   |
-| Live counter / timer text | DOM or Phaser text object     | Not an `assetMapping` image path                             |
-| Audio                     | Preloader loads contract path | Tier 2: `placeholder:gen-audio` spectral stub + sidecar JSON | TA replaces MP3     |
-| Audio                     | Event hook only, no load yet  | Tier 3: `emit('sfx:xxx')`                                    | TA binds play later |
-| Procedural debug overlay  | Phaser `Graphics` (minimal)   | Dev-only; remove or gate before ring gate                    |
-
-**Tier 3 rules:**
-
-1. **Never substitute Tier 3 for Tier 2** — if `layout-spec` / `assetMapping` names a `.webp` path, generate the placeholder file; do not draw a rectangle in `game/` code instead.
-2. **Log every Tier 3 exception** in `developer-log.md` § Placeholder materialization with one-line reason.
-3. **Keep code-draw ugly and minimal** — readability for debugging only; no time spent on visual design.
-
-#### ❌ Forbidden in build loop (rings 1–3)
-
-Do not use `playcraft image generate`, AI image tools, hand-drawn placeholder art, or effort on visual polish.
-
-- Build loop optimizes **playability + execution**, not presentation
-- Polished throwaway art wastes time and confuses ring 4 `ui_diff`
-- Artist / TA own production visuals in later rings
-
-#### Audio (Tier 2 stub vs Tier 3 event hook)
-
-| Situation                                                        | Tier       | Action                                                                            |
-| ---------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------- |
-| Preloader / `load.audio` already references contract `.mp3` path | **Tier 2** | `npm run placeholder:gen-audio` → spectral MP3 + sidecar JSON (+ spectrogram PNG) |
-| Gameplay only `emit('sfx:xxx')`, no load yet                     | **Tier 3** | Event hook only; log reason in `developer-log.md`                                 |
-| `playcraft skills link` delivered `.aiaudio`                     | **Tier 1** | Use linked file as-is                                                             |
-
-**Tier 2 audio** — default **spectral fingerprint** (ANS-style strokes from `label`); keeps loaders 404-free and makes each stub identifiable in a spectrogram:
-
-```bash
-npm run placeholder:gen-audio -- \
-  -o assets/audio/sfx/match.mp3 --label sfx_match --type sfx
-# outputs: match.mp3 + match.json + match.spectrogram.png
-
-npm run placeholder:gen-audio -- \
-  -o assets/audio/bgm/main_theme.mp3 --label bgm_main --type bgm
-
-# fully silent when needed:
-npm run placeholder:gen-audio -- -o assets/audio/sfx/match.mp3 --label sfx_match --silent
-```
-
-Batch: copy `templates/gen-placeholder-audio.template.mjs` → `ta-workspace/scripts/gen-placeholder-audio.mjs`.
-
-**Agent skill**: load [`skills/playable-placeholder/SKILL.md`](../../../skills/playable-placeholder/SKILL.md) for the full image + audio workflow.
-
-**Tier 3** (no load path yet):
-
-- Fire a named event (e.g. `emit('sfx:match')`) at the right moment — TA binds MP3 + play in ring 4.
-
-### Full asset binding flow
-
-```
-Step 1  List all visual resources expected by the minimal prototype
-        layout-spec assetMapping + first-level gameplay + basic UI + CTA + necessary VFX
-
-Step 2  Check which contract paths already have files (ref-flow or scaffold may have created them)
-        playcraft image info <path>  or  ls assets/images/...
-
-Step 3  For each existing path: read the atom's SKILL.md / ref / source to understand binding and usage
-
-Step 4  For every missing static image at a contract path:
-        add a row to ta-workspace/scripts/gen-placeholders.mjs → Tier 2
-        run: node ta-workspace/scripts/gen-placeholders.mjs
-        verify with playcraft image info <path>
-        For dynamic/non-file resources only → Tier 3 code-draw + log reason
-
-Step 5  Record Tier 1/2/3 result in developer-log.md § Placeholder materialization
-
-Step 6  Wire all paths in code from local contract paths only
-        → no hardcoded remote placeholder URLs, no runtime remote images, no inline base64 at this stage
-
-Step 7  npm run dev  →  all assets resolve, no 404s in console
-```
-
----
-
-## Atlas binding
-
-### What TA delivers
-
-When `layout-spec.md` defines an atlas group (≥2 elements of the same class), TA delivers **two files** side by side:
-
-```
-assets/images/tiles/tiles_atlas.webp   ← packed sprite image
-assets/images/tiles/tiles_atlas.json   ← frame map (auto-generated by playcraft image sprite-sheet)
-```
-
-The `atlasPath` and `sidecarPath` columns in the layout-spec atlas grouping table give the exact contract paths.
-
-### JSON sidecar format
-
-TA's `sprite-sheet` command auto-generates the `.json` sidecar. The structure Developer reads:
-
-```json
-{
-  "frames": {
-    "tile_gold": { "frame": { "x": 0, "y": 0, "w": 128, "h": 128 } },
-    "tile_blue": { "frame": { "x": 128, "y": 0, "w": 128, "h": 128 } },
-    "tile_red": { "frame": { "x": 256, "y": 0, "w": 128, "h": 128 } }
-  },
-  "meta": {
-    "size": { "w": 512, "h": 512 }
-  }
-}
-```
-
-Keys in `frames` are the **`frameId`** values from `layout-spec.md` → `assetMapping`. Developer looks up `frameId` → `frame.{x,y,w,h}` to get the sub-rect for that element.
-
-> **Note**: `animate` and `use-vfx` commands do NOT output a JSON sidecar. Grid params for those sheets are recorded by TA in `ta-log.md` → Sprite Grid Params. Developer reads them from there.
-
-### Binding pattern (Canvas)
-
-```js
-// Read frameId from layout-spec assetMapping, look up sub-rect from JSON
-const atlas = await loadImage('assets/images/tiles/tiles_atlas.webp');
-const frames = await fetch('assets/images/tiles/tiles_atlas.json').then((r) => r.json());
-
-function drawFrame(ctx, frameId, dx, dy) {
-  const { x, y, w, h } = frames.frames[frameId].frame;
-  ctx.drawImage(atlas, x, y, w, h, dx, dy, w, h);
-}
-
-// Usage
-drawFrame(ctx, 'tile_gold', screenX, screenY);
-```
-
-### Phase 1 vs Phase 2
-
-- **Phase 1**: no real atlas yet — use the local placeholder generator (`npm run placeholder:gen`) to contract path; still write the binding code against `atlasPath` + `frameId` so Phase 2 is a pure file drop-in with zero code changes
-- **Phase 2 (ui_rework)**: TA has delivered the real `.webp` + `.json`; verify both exist at contract paths (`playcraft image info <atlasPath>`), then confirm `drawFrame` resolves correctly in Dev
-
-### Contract rule
-
-`atlasPath` + `frameId` come from `layout-spec.md` — do not invent paths or frame names. If TA's JSON keys don't match the `frameId` in layout-spec, file a blocker (`routeTo: TA`).
-
----
-
-## index.html Skeleton (Phase 1)
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
-    <title>Playable Ad</title>
-    <style>
-      * {
-        margin: 0;
-        padding: 0;
-        box-sizing: border-box;
-      }
-      html,
-      body {
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-      }
-      canvas {
-        display: block;
-        width: 100%;
-        height: 100%;
-      }
-    </style>
-  </head>
-  <body>
-    <canvas id="game"></canvas>
-    <script>
-      // Game initialization — asset loading will be added in Phase 2
-      // Gameplay logic from game/gameplay/
-      // Config from game/config/
-
-      // CTA handler — **Ring 3+ only** (not a Ring 1/2 slice deliverable; defer until hook/CTA slices)
-      function onCTAClick() {
-        if (typeof mraid !== 'undefined') {
-          mraid.open('{{store_url}}');
-        } else if (typeof FbPlayableAd !== 'undefined') {
-          FbPlayableAd.onCTAClick();
-        } else if (typeof ExitApi !== 'undefined') {
-          ExitApi.exit();
-        } else {
-          window.open('{{store_url}}');
-        }
-      }
-    </script>
-  </body>
-</html>
-```
-
-**Phase 2 additions**: add asset loading (inline base64 or relative paths), connect gameplay logic, wire audio triggers, ensure ALL resources are inline (zero external requests).
-
----
-
-## PGS Implementation
-
-PGS (Playable Game State) is a JSON-driven state model that separates game rules from rendering. The gameplay Skill atom (if one exists via `skillRef`) provides the PGS schema and reducer — read its SKILL.md first.
-
-### Structure
-
-```json
-{
-  "entities": [{ "id": "tile_gold", "type": "tile", "color": "gold" }],
-  "rules": [{ "trigger": "match3", "minCount": 3, "action": "remove" }],
-  "algorithm": {
-    "gravity": "fall_down",
-    "refill": "random_from_bag"
-  },
-  "testCases": [{ "desc": "3 in a row clears", "board": "...", "expect": "..." }]
-}
-```
-
-| Field           | Source                                               |
-| --------------- | ---------------------------------------------------- |
-| `entities[].id` | `layout-spec.md` → `colorPalette.tileColors[].id`    |
-| `rules[]`       | `docs/design-brief.md` / `docs/design.md` core loop  |
-| `algorithm{}`   | gameplay Skill recipe, or design-brief spec          |
-| `testCases[]`   | **Write first** — test-first drives rule correctness |
-
-Key constraints come from layout-spec, not from invention:
-
-- Grid dimensions = `zones["board"].rect` / `assetSpec.tileSize`
-- Element types = `colorPalette.tileColors[]`
-- Element IDs = `colorPalette.tileColors[].id`
-
-> If a gameplay Skill atom exists, its SKILL.md defines the exact PGS fields and the reducer/dispatch API. The above is the general shape — defer to the Skill for any project that has one.