@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/phaser/game/contract/publish.ts

@@ -0,0 +1,141 @@
+import type { PlayablePhase, PlayableRuntimeContract, SceneManagerContract } from "./types.js";
+
+export type PublishPlayableBinding = {
+  engine?: string;
+  engineHandle?: unknown;
+  sceneManager: SceneManagerContract;
+  onDebugAutoPlay: () => void;
+  hideDebugUi?: () => void;
+  getCanvas?: () => HTMLCanvasElement | null;
+  getCaptureFps?: () => number;
+};
+
+/** DOM id for the on-screen one-click clear (debug auto-play) button. */
+export const DEBUG_CLEAR_BUTTON_ID = "playable-debug-clear";
+
+/** True when the page was opened with the `?debug=1` URL flag. */
+export function isDebugMode(): boolean {
+  try {
+    return new URLSearchParams(window.location.search).get("debug") === "1";
+  } catch {
+    return false;
+  }
+}
+
+/** Remove the on-screen one-click clear button (e.g. before MP4 capture). */
+export function removeDebugClearButton(): void {
+  if (typeof document === "undefined") return;
+  document.getElementById(DEBUG_CLEAR_BUTTON_ID)?.remove();
+}
+
+/**
+ * Mount a fixed, on-screen "一键通关 (one-click clear)" debug button that calls
+ * window.__playable.autoPlay(). Rendered ONLY when the page is opened with
+ * `?debug=1`, so production / capture stays clean. Idempotent.
+ *
+ * Ring 1 onward this button is a hard requirement (verified by verify:firstwin):
+ * every playable must expose a debug-gated one-click clear from the first ring.
+ */
+export function mountDebugClearButton(contract: PlayableRuntimeContract): void {
+  if (typeof document === "undefined" || !isDebugMode()) return;
+  if (document.getElementById(DEBUG_CLEAR_BUTTON_ID)) return;
+
+  const btn = document.createElement("button");
+  btn.id = DEBUG_CLEAR_BUTTON_ID;
+  btn.type = "button";
+  btn.textContent = "🐞 一键通关";
+  btn.setAttribute("data-debug", "1");
+  Object.assign(btn.style, {
+    position: "fixed",
+    left: "50%",
+    bottom: "16px",
+    transform: "translateX(-50%)",
+    zIndex: "999999",
+    padding: "10px 18px",
+    fontSize: "16px",
+    fontFamily: "system-ui, sans-serif",
+    color: "#1a1a1a",
+    background: "#FFD54A",
+    border: "2px solid #1a1a1a",
+    borderRadius: "10px",
+    boxShadow: "0 2px 8px rgba(0,0,0,0.35)",
+    cursor: "pointer",
+  } as Partial<CSSStyleDeclaration>);
+  btn.addEventListener("click", (e) => {
+    e.preventDefault();
+    try {
+      contract.autoPlay();
+    } catch (err) {
+      console.error("[playable-debug] one-click clear failed", err);
+    }
+  });
+
+  const mount = () => document.body.appendChild(btn);
+  if (document.body) mount();
+  else window.addEventListener("DOMContentLoaded", mount, { once: true });
+}
+
+/** Publish the neutral recorder/debug entry point after the main scene is ready. */
+export function publishPlayableRuntime(binding: PublishPlayableBinding): PlayableRuntimeContract {
+  const contract: PlayableRuntimeContract = {
+    engine: binding.engine ?? "unknown",
+    engineHandle: binding.engineHandle,
+    sceneManager: binding.sceneManager,
+    getState: () => ({
+      currentPhase: binding.sceneManager.currentPhase,
+      isGameOver: binding.sceneManager.isGameOver(),
+    }),
+    autoPlay: binding.onDebugAutoPlay,
+    start: binding.onDebugAutoPlay,
+  };
+  // Always provide hideDebugUi: it removes the on-screen debug button (for clean
+  // capture) and delegates to any engine-specific cleanup the binding supplied.
+  contract.hideDebugUi = () => {
+    removeDebugClearButton();
+    binding.hideDebugUi?.();
+  };
+  if (binding.getCanvas) contract.getCanvas = binding.getCanvas;
+  if (binding.getCaptureFps) contract.getCaptureFps = binding.getCaptureFps;
+  window.__playable = contract;
+  mountDebugClearButton(contract);
+  return contract;
+}
+
+/** Legacy Phaser MainScene shape — prefer window.__playable for new engines. */
+export interface PlayableMainSceneLike {
+  sceneManager?: SceneManagerContract;
+  _onDebugAutoPlay?(): void;
+}
+
+/**
+ * Validate that a scene satisfies the legacy Phaser harness contract.
+ * Neutral engines should rely on publishPlayableRuntime only.
+ */
+export function assertPlayableSceneContract(scene: PlayableMainSceneLike): void {
+  const problems: string[] = [];
+
+  if (!scene.sceneManager) {
+    problems.push("scene.sceneManager is missing");
+  } else {
+    if (typeof scene.sceneManager.currentPhase !== "string") {
+      problems.push("sceneManager.currentPhase must be a PlayablePhase string");
+    }
+    if (typeof scene.sceneManager.isGameOver !== "function") {
+      problems.push("sceneManager.isGameOver() must be a function");
+    }
+  }
+  if (typeof scene._onDebugAutoPlay !== "function") {
+    problems.push("scene._onDebugAutoPlay() must be a function");
+  }
+
+  if (problems.length > 0) {
+    const msg =
+      "[playable-contract] MainScene violates the recording/debug harness contract:\n" +
+      problems.map((p) => `  - ${p}`).join("\n") +
+      "\nSee game/runtime-contract.ts — record:mp4 and one-click clear depend on these hooks.";
+    console.error(msg);
+    throw new Error(msg);
+  }
+}
+
+export type { PlayablePhase, PlayableRuntimeContract, SceneManagerContract };

package/project-templates/phaser/game/contract/types.ts

@@ -0,0 +1,34 @@
+/** Lifecycle phases the recorder waits on (HOOK → … → ENDCARD). */
+export type PlayablePhase = "HOOK" | "TUTORIAL" | "GAMEPLAY" | "ENDCARD";
+
+/** Minimal scene-state surface the harness reads. */
+export interface SceneManagerContract {
+  currentPhase: PlayablePhase;
+  isGameOver(): boolean;
+}
+
+/** Engine-neutral recorder/debug surface. Do not attach harness methods to the engine object. */
+export interface PlayableRuntimeContract {
+  engine: string;
+  /** Opaque engine handle (Phaser.Game, THREE.WebGLRenderer context owner, etc.). */
+  engineHandle?: unknown;
+  sceneManager: SceneManagerContract;
+  getState(): { currentPhase: PlayablePhase; isGameOver: boolean };
+  autoPlay(): void;
+  start(): void;
+  /** Optional: hide debug UI before capture. */
+  hideDebugUi?(): void;
+  /** Optional: canvas for record bridge when engine handle is opaque. */
+  getCanvas?(): HTMLCanvasElement | null;
+  /** Optional: target capture FPS hint for record bridge. */
+  getCaptureFps?(): number;
+}
+
+declare global {
+  interface Window {
+    __playable?: PlayableRuntimeContract;
+    __game?: unknown;
+  }
+}
+
+export {};

package/project-templates/phaser/game/index.ts

@@ -0,0 +1,81 @@
+import Phaser from "phaser";
+import { GAME_CONFIG } from "./config/game-config";
+import {
+  bindPlayableScene,
+  registerPlayable,
+  type PlayablePhase,
+  type SceneManagerContract,
+} from "./runtime-contract";
+
+/**
+ * Minimal playable stub for the PlayCraft project template.
+ * Replace with real game implementation during `development` stage.
+ *
+ * The stub already satisfies the recording/debug harness contract
+ * (see game/runtime-contract.ts) so `record:mp4` and one-click clear work
+ * from second 0 — keep these hooks wired when you replace the game.
+ */
+
+class MainScene extends Phaser.Scene {
+  constructor() {
+    super({ key: "MainScene" });
+  }
+
+  create() {
+    this.cameras.main.setBackgroundColor("#2A1500");
+
+    const cx = GAME_CONFIG.DESIGN_WIDTH / 2;
+
+    this.add
+      .text(cx, 600, "PlayCraft Template", {
+        fontSize: "48px",
+        color: "#D4A838",
+        fontFamily: "sans-serif",
+      })
+      .setOrigin(0.5);
+
+    this.add
+      .text(cx, 760, "Replace game/ with real implementation", {
+        fontSize: "28px",
+        color: "#FFFFFF",
+        fontFamily: "sans-serif",
+      })
+      .setOrigin(0.5);
+
+    const sceneManager: SceneManagerContract = {
+      currentPhase: "HOOK" as PlayablePhase,
+      isGameOver: () => sceneManager.currentPhase === "ENDCARD",
+    };
+
+    const onDebugAutoPlay = () => {
+      sceneManager.currentPhase = "ENDCARD";
+      this.add
+        .text(cx, 960, "ENDCARD / CTA", {
+          fontSize: "56px",
+          color: "#FFD700",
+          fontFamily: "sans-serif",
+        })
+        .setOrigin(0.5);
+    };
+
+    bindPlayableScene(this, { sceneManager, onDebugAutoPlay });
+  }
+}
+
+export function startGame(parentId: string) {
+  const config = {
+    type: Phaser.AUTO,
+    width: GAME_CONFIG.DESIGN_WIDTH,
+    height: GAME_CONFIG.DESIGN_HEIGHT,
+    parent: parentId,
+    backgroundColor: "#2A1500",
+    disableVisibilityChange: true,
+    scale: {
+      mode: Phaser.Scale.FIT,
+      autoCenter: Phaser.Scale.CENTER_BOTH,
+    },
+    scene: [MainScene],
+  } as Phaser.Types.Core.GameConfig;
+
+  return registerPlayable(new Phaser.Game(config));
+}

package/project-templates/phaser/game/runtime-contract.ts

@@ -0,0 +1,28 @@
+/**
+ * Playable ⇄ Harness runtime contract — re-export facade.
+ *
+ * Engine-neutral types live in game/contract/; Phaser bindings in game/adapters/phaser.ts.
+ * Keep symbol names in sync with skills/playable-record and verify_runtime_contract.js.
+ */
+
+export type {
+  PlayablePhase,
+  PlayableRuntimeContract,
+  SceneManagerContract,
+} from "./contract/types.js";
+
+export {
+  publishPlayableRuntime,
+  assertPlayableSceneContract,
+  mountDebugClearButton,
+  removeDebugClearButton,
+  isDebugMode,
+  DEBUG_CLEAR_BUTTON_ID,
+  type PublishPlayableBinding,
+} from "./contract/publish.js";
+
+export {
+  registerPlayable,
+  bindPlayableScene,
+  type PlayableMainScene,
+} from "./adapters/phaser.js";

package/project-templates/phaser/globals.d.ts

@@ -0,0 +1,51 @@
+declare module "*.png" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.webp" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.jpg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.jpeg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.svg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.gif" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.mp3" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.ogg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.wav" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.m4a" {
+  const src: string;
+  export default src;
+}
+
+declare const __DEV__: boolean;

package/project-templates/phaser/index.css

@@ -0,0 +1,34 @@
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+  -webkit-tap-highlight-color: transparent;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: #000;
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+  overscroll-behavior: none;
+  touch-action: none;
+}
+
+#game-container {
+  width: 100%;
+  height: 100%;
+  padding-top: env(safe-area-inset-top);
+  padding-right: env(safe-area-inset-right);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+}
+
+canvas {
+  display: block;
+}

package/project-templates/phaser/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
+    />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <meta name="format-detection" content="telephone=no" />
+    <title>PlayCraft Playable</title>
+  </head>
+  <body>
+    <div id="game-container"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/project-templates/phaser/main.ts

@@ -0,0 +1,9 @@
+import "./index.css";
+import { startGame } from "./game/index";
+
+let game = startGame("game-container");
+
+window.addEventListener("resize", () => {
+  game.destroy?.(true);
+  game = startGame("game-container");
+});

package/project-templates/phaser/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "playcraft-game",
+  "version": "0.1.0",
+  "playcraftTemplateVersion": "0.3.2-alpha.0",
+  "description": "PlayCraft Playable Ads project",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "dev:start": "node skills/_shared/scripts/dev-start.mjs --root=.",
+    "dev:stop": "node skills/_shared/scripts/dev-start.mjs --root=. --stop",
+    "build": "vite build && npm run verify:build",
+    "build:raw": "vite build",
+    "verify:build": "node skills/playable-record/scripts/verify-build.mjs --root=.",
+    "preview": "vite preview",
+    "ensure:project": "node skills/_shared/scripts/ensure-project.mjs --root=.",
+    "ring:gate": "node skills/../.claude/hooks/gate-runner.mjs",
+    "workflow:doctor": "node skills/_shared/scripts/workflow-doctor.mjs --root=.",
+    "workflow:doctor:strict": "node skills/_shared/scripts/workflow-doctor.mjs --root=. --strict",
+    "state:set": "node skills/_shared/scripts/state-set.mjs --root=.",
+    "state:get": "node skills/_shared/scripts/state-get.mjs --root=.",
+    "state:advance-ring": "node skills/_shared/scripts/state-advance-ring.mjs --root=.",
+    "slice:set": "node skills/_shared/scripts/slice-set.mjs --root=.",
+    "verify:slice": "node skills/playable-record/scripts/verify-slice.mjs --root=. --use-dev",
+    "verify:slice-artist": "node skills/playable-record/scripts/verify-slice-artist.mjs --root=.",
+    "verify:slice-ta": "node skills/playable-record/scripts/verify-slice-ta.mjs --root=.",
+    "harness:smoke": "node skills/_shared/scripts/harness-smoke.mjs --root=.",
+    "context:budget": "node skills/_shared/scripts/context-budget.mjs --root=.",
+    "verify:env": "node skills/_shared/scripts/verify-env.mjs --root=.",
+    "skills:check": "node skills/_shared/scripts/skills-check.mjs --root=.",
+    "verify:ui": "python3 skills/playable-verify-ui/scripts/run_all.py",
+    "verify:ui:assets": "python3 skills/playable-verify-ui/scripts/run_all.py --only assets",
+    "verify:ui:layout": "python3 skills/playable-verify-ui/scripts/run_all.py --only layout",
+    "record:mp4": "node skills/playable-record/scripts/record-playable.mjs --root=. --use-dev",
+    "record:focus": "node skills/playable-record/scripts/record-playable.mjs --root=. --use-dev --focus",
+    "typecheck": "tsc --noEmit",
+    "verify:contract": "node skills/playable-record/scripts/verify-contract.mjs --root=. --use-dev",
+    "verify:lifecycle": "node skills/playable-record/scripts/verify-lifecycle.mjs --root=. --use-dev",
+    "verify:firstwin": "node skills/playable-record/scripts/verify-firstwin.mjs --root=. --use-dev",
+    "playground": "node skills/playable-focus/scripts/playground.mjs --root=.",
+    "sweep:L1": "node skills/playable-focus/scripts/playground.mjs --root=. sweep L1",
+    "sweep:G1": "node skills/playable-focus/scripts/playground.mjs --root=. sweep G1",
+    "repack:frames": "python3 skills/playable-fx-peak/scripts/repack-frame-sequence.py",
+    "mark:slices": "python3 skills/playable-art/scripts/import-gpt-art-sheets-v2.py --mark-only",
+    "import:gpt-art": "python3 skills/playable-art/scripts/import-gpt-art-sheets-v2.py",
+    "review:assets": "python3 skills/playable-art/scripts/review-processed-assets.py --root=.",
+    "verify:asset-review": "python3 skills/playable-art/scripts/review-processed-assets.py --root=. --strict --json",
+    "verify:slice-plan": "python3 skills/playable-verify-ui/scripts/verify_slice_plan.py --root=.",
+    "build-atlas": "python3 skills/playable-art/scripts/build-atlas.py",
+    "record:mp4:install": "playwright install chromium",
+    "bootstrap:playground": "node skills/playable-focus/scripts/bootstrap-playground.mjs --root=.",
+    "validate:frame-anchors": "python3 skills/playable-fx-peak/scripts/validate-frame-anchors.py",
+    "placeholder:gen": "python3 skills/_shared/scripts/gen-placeholder.py",
+    "placeholder:pack-sheet": "node skills/_shared/scripts/placeholder-pack-sheet.mjs --root=.",
+    "placeholder:gen-audio": "python3 skills/_shared/scripts/gen-placeholder-audio.py",
+    "verify:placeholders": "node skills/_shared/scripts/verify-placeholders.mjs --root=.",
+    "verify:fusion": "node skills/playable-record/scripts/verify-fusion.mjs --root=. --use-dev",
+    "verify:visual-ring1": "node skills/playable-record/scripts/verify-visual-ring1.mjs --root=. --use-dev",
+    "verify:visual-ring2": "node skills/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=2 --use-dev",
+    "verify:visual-ring3": "node skills/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=3 --use-dev",
+    "verify:vlm-video": "node skills/playable-record/scripts/verify-vlm-video.mjs --root=.",
+    "verify:visual": "python3 skills/playable-verify-ui/scripts/verify_visual.py --root=.",
+    "verify:bg-clean": "python3 skills/playable-verify-ui/scripts/verify_bg_clean.py --root=.",
+    "verify:tile-consistency": "python3 skills/playable-verify-ui/scripts/verify_tile_consistency.py --root=.",
+    "verify:text-overlap": "python3 skills/playable-verify-ui/scripts/verify_text_overlap.py --root=.",
+    "verify:vision": "python3 skills/playable-verify-ui/scripts/verify_vision_evidence.py --root=.",
+    "verify:asset-code-sync": "node skills/_shared/scripts/verify-asset-code-sync.mjs --root=.",
+    "verify:atom-conformance": "node skills/_shared/scripts/verify-atom-conformance.mjs --project=."
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.19.8",
+    "playwright": "^1.59.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.3"
+  }
+}

package/project-templates/phaser/skills/README.md

@@ -0,0 +1,52 @@
+# Template Skills — 九步核心集（短名）
+
+## 命名（新 → 旧，口语仍可用）
+
+| 新目录名                  | 旧名                            | 用户可说                       |
+| ------------------------- | ------------------------------- | ------------------------------ |
+| **playable-validate**     | playable-video-validate-loop    | video validate loop / 整片优化 |
+| **playable-verify-ui**    | playable-ui-optimization        | ui optimization / 检查 UI      |
+| **playable-record**       | playable-record-playback        | 录屏                           |
+| **playable-debug**        | playable-debug-playback         | 一键通关                       |
+| **playable-art**          | playable-gpt-art-pipeline       | gpt art / 换美术               |
+| **playable-fx-peak**      | playable-frame-fx-peak-pipeline | peak pipeline / 帧光效         |
+| **playable-fx-decompose** | playable-decompose-fx           | decompose / 碎裂               |
+| **playable-animate**      | playable-animation-polish       | 动效手感                       |
+| **playable-focus**        | playable-focus-playground       | L→G / focus lab                |
+
+## 已删除 skill → 内容并入哪里
+
+| 已删                             | 并入                                                                          |
+| -------------------------------- | ----------------------------------------------------------------------------- |
+| playable-ui-regression-checklist | `playable-validate/validation-rules.md` §⑥ + `references/checklist-detail.md` |
+| playable-gpt-fx-frame-animation  | `playable-fx-peak` § GPT 出图与 A/B                                           |
+| playable-ui-reference-matching   | `playable-art` § Reference Matching                                           |
+| playable-frame-text-layout       | `playable-verify-ui` § Frame+Text + `measure_frame_content.py`                |
+| playable-performance-interaction | `playable-animate` § Performance + references                                 |
+| playable-single-html-bundle      | `playable-validate/references/single-html-bundle.md`                          |
+
+## Skill 索引
+
+| 用户意图                    | Skill                                                     | 角色                            |
+| --------------------------- | --------------------------------------------------------- | ------------------------------- |
+| Develop 占位资产            | [playable-placeholder](./playable-placeholder/SKILL.md)   | **Developer** (rings 1–3 build) |
+| 整片 / 当前页面（**默认**） | [playable-validate](./playable-validate/SKILL.md)         | TA / Reviewer                   |
+| 静态素材 / layout           | [playable-verify-ui](./playable-verify-ui/SKILL.md)       |
+| 录屏                        | [playable-record](./playable-record/SKILL.md)             |
+| 一键通关                    | [playable-debug](./playable-debug/SKILL.md)               |
+| GPT 美术                    | [playable-art](./playable-art/SKILL.md)                   |
+| 帧 ADD / repack             | [playable-fx-peak](./playable-fx-peak/SKILL.md)           |
+| 破碎                        | [playable-fx-decompose](./playable-fx-decompose/SKILL.md) |
+| 动效 / 卡顿                 | [playable-animate](./playable-animate/SKILL.md)           |
+| L→G                         | [playable-focus](./playable-focus/SKILL.md)               |
+
+Agent 起手：[\_shared/agent-prep.md](./_shared/agent-prep.md) → `npm run ensure:project`
+
+## 同步与漂移治理
+
+- **`skills/` 下的本地 playable skill 唯一同步源**：`node skills/_shared/scripts/sync-template-skills.mjs`。
+  不要手动逐文件复制或从其它路径拉取；任何对这九个 skill 的更新都应回到 monorepo 源、经此脚本同步，避免多源漂移。
+- **`.claude/skills/` 下的平台 skill 影子副本**：模板对少数平台 skill（`playcraft-image-generation`、
+  `playcraft-audio-generation`、`playcraft-sprite-generation`）保留静态副本并优先于 `@playcraft/skills` 包版本。
+  这是有意 fork——用 `npm run skills:check` 检测它们是否已与包版本漂移（`--strict` 在漂移时非零退出），
+  确保 fork 是"刻意保留"而非"忘记更新"。