@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/.claude/agents/refs/developer-dev-handoff.md

@@ -0,0 +1,152 @@
+# Developer Dev Handoff (L2)
+
+Use when Developer is validating preview quality, recording ready-state, or routing upstream blockers.
+
+This file is a handoff/verification companion. Role ownership stays in `developer.md`; runtime routing and STOP ownership stay in the shared workflow docs.
+
+## Dev command
+
+```bash
+npm run dev:start   # starts persistent dev server + records the real devUrl
+# npm run dev:stop  # only when intentionally tearing down before Ring Gate
+```
+
+- **Not** `playcraft start`, and **not** a bare `npm run dev`. `dev:start` wraps the project's `scripts.dev` and additionally:
+  - detects the actual listening port from Vite output (handles port drift when 3000 is taken),
+  - appends `?debug=1`,
+  - writes `devUrl` through the same programmatic state layer `state:set` uses.
+- **Do not** read a port from the terminal or hand-edit `devUrl` — `dev:start` is the source of truth for it.
+- Prefer leaving the server running for Reviewer and Ring Gate user preview; **do not `pkill` vite before Ring Gate** (use `npm run dev:stop` if you must).
+- **`verify:contract` / `verify:firstwin` / `record:mp4` spawn their own dev server** — run them directly; **never** start a separate dev server just to satisfy verify scripts.
+
+## Verify scripts (self-managed server)
+
+```bash
+npm run verify:contract   # boots dev server internally, exits when done
+npm run verify:firstwin   # same — no manual npm run dev needed
+```
+
+Do **not** run `npm run dev & sleep && curl` before verify commands. The scripts auto-detect the listening port from Vite stdout.
+
+## Dev iteration rhythm
+
+During integration, repeat:
+
+1. Change code / wire assets
+2. `npm run dev:start` (HMR usually suffices; rerun only to restart)
+3. Self-check UI + gameplay + runtime (checklists below)
+4. Log in `developer-log.md` → **Dev self-check**
+5. If upstream issue → blockers + ICP + STOP (orchestrator routes TA/Artist)
+
+**Do not** wait until the last minute for a single Dev pass.
+
+## UI checklist (vs MC + layout-spec)
+
+| Check                                              | Source                                        |
+| -------------------------------------------------- | --------------------------------------------- |
+| Zones and hierarchy match layout-spec              | `docs/layout-spec.md`                         |
+| Colors / mood match approved style                 | `docs/style-exploration.md`, ring 3 locked MC |
+| Element placement matches storyboard Visual Intent | Master Composite frames                       |
+| Text-as-image assets visible, correct aspect       | `assetMapping` paths                          |
+| No broken images / wrong sprites / style drift     | Dev browser                                   |
+| Mobile viewport (e.g. 750×1334) acceptable         | Dev browser resize                            |
+
+## Gameplay checklist (vs DESIGN.md + PGS)
+
+> Gameplay contract source is `docs/DESIGN.md` in every ring. `design-brief.md` only exists from ring 2+ as supplementary process detail.
+
+| Check                                                 | Source            |
+| ----------------------------------------------------- | ----------------- |
+| Hook → Tutorial → Gameplay → End Card flow            | `docs/DESIGN.md`  |
+| Rules, scoring, win/lose match Game Designer contract | `DESIGN.md` + PGS |
+| **First level guaranteed success**                    | atom-tree / PGS   |
+| Near-Win and difficulty feel as specified             | `DESIGN.md`       |
+| CTA on End Card                                       | runtime test      |
+
+## Runtime checklist
+
+- No white screen or blocking console errors
+- Full playthrough without dead ends
+- BGM/SFX at correct events
+- State machine stable; CTA handler fires (`mraid` / `FbPlayableAd` / `ExitApi` as applicable)
+
+## devUrl recording
+
+`devUrl` is written **programmatically** by `npm run dev:start` (real port + `?debug=1`). Do not hand-edit it. The remaining Dev Preview fields are set via `npm run state:set`:
+
+| Field            | When                                                 | Written by          |
+| ---------------- | ---------------------------------------------------- | ------------------- |
+| `devUrl`         | When `npm run dev:start` runs                        | `dev:start` (auto)  |
+| `devStatus`      | `pending` → `ready` or `blocked_upstream` / `failed` | `npm run state:set` |
+| `devStartedBy`   | `developer`                                          | `npm run state:set` |
+| `devLastChecked` | ISO timestamp after each meaningful Dev pass         | `npm run state:set` |
+
+Also note devUrl in `docs/developer-log.md` → **Dev self-check** (copy from `dev:start` output).
+
+## Upstream blocker template
+
+Add to `developer-log.md` → **## Upstream blockers**:
+
+```markdown
+| Path              | Issue   | Expected                           | routeTo | Status |
+| ----------------- | ------- | ---------------------------------- | ------- | ------ |
+| assets/ui/foo.png | missing | 256×256 PNG per layout-spec zone A | TA      | open   |
+```
+
+In `docs/intent-clarifications.md`:
+
+- **Context**: what Dev showed (screenshot description or path)
+- **Gap**: vs MC / contract / design-brief
+- **Acceptance**: exact path, dimensions, style, or audio mood required
+- **routeTo**: TA | Artist | Game Designer
+
+Set state programmatically:
+
+```bash
+npm run state:set -- \
+  devStatus=blocked_upstream \
+  devBlockers='[{"routeTo":"technical-artist","issue":"missing production asset","status":"open"}]'
+```
+
+**STOP** after filing — wait for orchestrator to re-invoke upstream role, then **re-run Dev loop**.
+
+## After rework — re-verify checklist
+
+1. Confirm blocker paths exist on disk (`ls`, `playcraft image info` if needed)
+2. `npm run dev:start`
+3. Re-run UI + gameplay + runtime checklists for affected areas
+4. Close blocker rows (`status: resolved`) or escalate if still wrong
+5. Only then set `devStatus: ready` (no open `devBlockers`) and handoff `next_orchestrator_action: "Invoke @reviewer gameplay_conformance"`
+
+## Integration complete — verify before ready
+
+When TA's production assets land (Phase 2 / ui_rework), run this before setting `devStatus: ready`:
+
+| Requirement                                                     | How to verify                            |
+| --------------------------------------------------------------- | ---------------------------------------- |
+| Entry point is `game/index.html`                                | `ls game/index.html`                     |
+| All asset references use relative paths                         | Read game code                           |
+| No Node.js APIs in `game/`                                      | Code review                              |
+| No dynamic imports or CDN references                            | `grep -r "import(" game/`                |
+| Zero external requests                                          | Browser console + `grep -r "http" game/` |
+| Every `tileColors[].id` has image at `assetMapping.visualAsset` | `layout-spec` + `ls`                     |
+| All SFX files exist per `assetMapping`                          | `layout-spec` + `ls`                     |
+| Background at correct path                                      | `layout-spec` + `ls`                     |
+| Atlas `.webp` + `.json` bound with correct `frameId`            | `playcraft image info <atlasPath>`       |
+| Board position = `zones["board"].rect`                          | layout-spec                              |
+| Elements positioned per `zones[].rect`                          | Dev browser                              |
+
+> **`playcraft build` is not required** for `devStatus: ready` or project `done`.
+
+## Dev ready checklist (`devStatus: ready` — all required)
+
+- [ ] UI checklist pass in Dev
+- [ ] Gameplay checklist pass in Dev
+- [ ] Runtime checklist pass in Dev
+- [ ] No open rows in Upstream blockers / `devBlockers`
+- [ ] `devUrl` recorded and server reachable
+- [ ] `developer-log.md` Dev self-check complete
+- [ ] `npm run ensure:project` executed (prepares optimization toolkit)
+- [ ] `npm run verify:ui` PASS or only expected warnings (catches asset/layout drift)
+- [ ] Headed full-playthrough baseline recorded: `npm run record:mp4 -- --headed --fps=60`
+- [ ] **Not** required: `playcraft build`, user running terminal commands

package/project-templates/threejs/.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` / `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.

package/project-templates/threejs/.claude/agents/refs/developer-legacy-fallback.md

@@ -0,0 +1,15 @@
+# Developer Legacy Fallback
+
+Use this reference only when `dispatchPacket` is null and `sliceState` is empty.
+
+This preserves the older growth-ring build path for existing projects. It is not part of slice-axis dispatch.
+
+Legacy behavior:
+
+- Read `npm run state:get -- --json` and follow the disclosed current action.
+- Complete the upstream intake required by the legacy template before editing runtime files.
+- Implement only the legacy target disclosed by orchestrator state.
+- Run the disclosed verification scripts before claiming readiness.
+- Route blockers through state handoff instead of expanding scope.
+
+When `sliceState` exists, return to the main Developer role contract.