@playcraft/cli 0.0.57 → 0.0.58

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

@@ -0,0 +1,432 @@
+# 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.