@playcraft/cli 0.0.43 → 0.0.46

package/dist/commands/tools-detect.js

@@ -0,0 +1,56 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { handleError } from './tools-utils.js';
+function makeClient(opts) {
+    if (opts.apiUrl || opts.token) {
+        if (opts.apiUrl)
+            process.env.PLAYCRAFT_API_URL = opts.apiUrl;
+        if (opts.token)
+            process.env.PLAYCRAFT_SANDBOX_TOKEN = opts.token;
+    }
+    return new AgentApiClient();
+}
+export async function runDetect(opts) {
+    const imagePath = resolve(opts.image);
+    const outputPath = resolve(opts.output);
+    const relSourcePath = relative(process.cwd(), imagePath).split(sep).join('/');
+    const sourcePath = relSourcePath && !relSourcePath.startsWith('..') ? relSourcePath : basename(imagePath);
+    const imageBase64 = readFileSync(imagePath).toString('base64');
+    const client = makeClient({ apiUrl: opts.apiUrl, token: opts.token });
+    const result = await client.post('/detect', {
+        imageBase64,
+        sourcePath,
+        prompts: opts.prompt.length > 0 ? opts.prompt : undefined,
+    });
+    const payload = {
+        detections: result.detections.map((det) => ({
+            sourcePath: det.sourcePath ?? sourcePath,
+            frame: det.frame ?? null,
+            box: det.box,
+            className: det.className,
+            confidence: det.confidence,
+        })),
+    };
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    console.log(`[tools detect] ${payload.detections.length} detections → ${outputPath}`);
+}
+export function registerDetectCommand(tools) {
+    tools
+        .command('detect')
+        .description('Backend SAM3 detect → JSON for npm run verify:vision -- --detections')
+        .requiredOption('--image <path>', 'Screenshot or asset path')
+        .option('--output <path>', 'Detections JSON output', 'validate/vision/detections.json')
+        .option('--api-url <url>', 'Backend API URL override')
+        .option('--token <token>', 'PAT or sandbox token override')
+        .option('--prompt <text>', 'Open-vocab SAM3 prompt (repeatable)', (value, prev) => [...prev, value], [])
+        .action(async (opts) => {
+        try {
+            await runDetect(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}

package/dist/commands/tools-generation.js

@@ -388,6 +388,7 @@ export function registerGenerationCommands(tools) {
         .requiredOption('--prompt <text>', 'BGM 描述，如 "轻快休闲游戏配乐"')
         .option('--style <style>', '音乐风格，如 casual / epic / sci-fi / retro')
         .option('--bpm <bpm>', '目标 BPM', parseInt)
+        .option('--fallback-placeholder', 'On API failure (503/missing key), skip hard fail with explicit placeholder guidance')
         .requiredOption('--output <path>', '保存路径，如 ./assets/audio/bgm.mp3')
         .action(async (opts) => {
         try {
@@ -411,6 +412,26 @@ export function registerGenerationCommands(tools) {
             console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
         }
         catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const apiUnavailable = /503|MuleRouter|API key|No MuleRouter/i.test(msg);
+            if (apiUnavailable) {
+                console.error(`Error: ${msg}`);
+                console.error('Hint: BGM API unavailable — run `npm run placeholder:gen-audio` or re-run with --fallback-placeholder');
+                if (opts.fallbackPlaceholder) {
+                    mkdirSync(dirname(opts.output), { recursive: true });
+                    writeFileSync(opts.output.replace(/\.[^.]+$/, '.placeholder.json'), JSON.stringify({
+                        type: 'bgm',
+                        placeholder: true,
+                        reason: msg,
+                        output: opts.output,
+                        suggestedCommand: 'npm run placeholder:gen-audio',
+                        generatedAt: new Date().toISOString(),
+                    }, null, 2));
+                    console.warn(`⚠️  Wrote placeholder marker — generate audio before Ring Gate: ${opts.output}`);
+                    return;
+                }
+                process.exit(1);
+            }
             handleError(e);
         }
     });

package/dist/commands/tools-video-review.js

@@ -0,0 +1,100 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { handleError } from './tools-utils.js';
+function makeClient(opts) {
+    if (opts.apiUrl)
+        process.env.PLAYCRAFT_API_URL = opts.apiUrl;
+    if (opts.token)
+        process.env.PLAYCRAFT_SANDBOX_TOKEN = opts.token;
+    return new AgentApiClient();
+}
+function fileToBase64DataUrl(path) {
+    const data = readFileSync(resolve(path));
+    const mimeType = path.toLowerCase().endsWith('.webm')
+        ? 'video/webm'
+        : path.toLowerCase().endsWith('.mov')
+            ? 'video/quicktime'
+            : 'video/mp4';
+    return `data:${mimeType};base64,${data.toString('base64')}`;
+}
+function parseContext(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`--context-json is not valid JSON: ${e.message}`);
+    }
+}
+function readContextFile(path) {
+    if (!path)
+        return undefined;
+    const text = readFileSync(resolve(path), 'utf8');
+    // Naive extraction of key sections from DESIGN.md
+    const designSummary = extractSection(text, 'Game Concept', 'Summary') || extractSection(text, '设计概要', '核心玩法');
+    const hook = extractSection(text, 'Hook', 'First Action') || extractSection(text, 'Hook', '核心操作');
+    const firstAction = extractSection(text, 'First Action', 'CTA') || extractSection(text, '核心操作', 'CTA');
+    const ctaText = extractSection(text, 'CTA', 'Endcard') || extractSection(text, 'CTA', '结束画面');
+    return {
+        designSummary,
+        hook,
+        firstAction,
+        ctaText,
+    };
+}
+function extractSection(text, startMarker, endMarker) {
+    const startIdx = text.indexOf(startMarker);
+    if (startIdx < 0)
+        return undefined;
+    const endIdx = text.indexOf(endMarker, startIdx + startMarker.length);
+    const slice = text.slice(startIdx + startMarker.length, endIdx > 0 ? endIdx : undefined);
+    return slice.replace(/^[\s\n:：]+|[\s\n]+$/g, '').slice(0, 400) || undefined;
+}
+export async function runVideoReview(opts) {
+    const videoPath = resolve(opts.video);
+    const outputPath = resolve(opts.output);
+    const context = opts.contextJson ? parseContext(opts.contextJson) : readContextFile(opts.contextFile);
+    const ring = opts.ring ? Number.parseInt(opts.ring, 10) : undefined;
+    const request = {
+        videoBase64: fileToBase64DataUrl(videoPath),
+        sourcePath: videoPath,
+        context,
+        ...(opts.model && { model: opts.model }),
+        ...(opts.provider && { provider: opts.provider }),
+        ...(opts.tier && { tier: opts.tier }),
+        ...(ring && { ring }),
+    };
+    const client = makeClient({ apiUrl: opts.apiUrl, token: opts.token });
+    const result = await client.post('/analyze-video', request);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+    console.log(`[tools analyze-video] ok=${result.ok} findings=${result.findings.length} → ${outputPath}`);
+    for (const f of result.findings) {
+        console.log(`  ${f.status.toUpperCase()} ${f.severity} ${f.className}: ${f.message.slice(0, 120)}`);
+    }
+}
+export function registerVideoReviewCommand(tools) {
+    tools
+        .command('analyze-video')
+        .description('Backend VLM video semantic review → JSON findings')
+        .requiredOption('--video <path>', 'MP4/WebM/MOV path')
+        .option('--output <path>', 'Output JSON path', 'validate/vlm-video.json')
+        .option('--context-file <path>', 'DESIGN.md or similar context file')
+        .option('--context-json <json>', 'JSON string with designSummary/hook/firstAction/ctaText')
+        .option('--model <ref>', 'Model override, e.g. moonshot/kimi-k2.6 or google/gemini-2.5-flash-preview-05-20')
+        .option('--provider <name>', 'Provider override, e.g. moonshot or google')
+        .option('--tier <fast|thorough>', 'Review tier: fast=screening, thorough=deep review')
+        .option('--ring <1-4>', 'Growth-ring iteration; adapts the review rubric')
+        .option('--api-url <url>', 'Backend API URL override')
+        .option('--token <token>', 'PAT or sandbox token override')
+        .action(async (opts) => {
+        try {
+            await runVideoReview(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}

package/dist/commands/tools.js

@@ -1,6 +1,8 @@
 import { registerGenerationCommands } from './tools-generation.js';
 import { registerProjectCommands } from './tools-project.js';
 import { register3DCommands } from './tools-3d.js';
+import { registerDetectCommand } from './tools-detect.js';
+import { registerVideoReviewCommand } from './tools-video-review.js';
 export function registerToolsCommands(program) {
     const tools = program
         .command('tools')
@@ -8,4 +10,6 @@ export function registerToolsCommands(program) {
     registerGenerationCommands(tools);
     registerProjectCommands(tools);
     register3DCommands(tools);
+    registerDetectCommand(tools);
+    registerVideoReviewCommand(tools);
 }

package/dist/index.js

@@ -23,6 +23,7 @@ import { registerPrefabCommands } from './commands/prefab.js';
 import { registerRecommendCommands } from './commands/recommend.js';
 import { registerRemixCommands } from './commands/remix.js';
 import { registerSkillsCommands } from './commands/skills.js';
+import { registerPradCommands } from './commands/prad.js';
 import { register3DCommands } from './commands/3d.js';
 import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -357,6 +358,7 @@ registerRecommendCommands(program);
 registerRemixCommands(program);
 // 开发时 Skill 发现与脚手架 (playcraft skills <command>)
 registerSkillsCommands(program);
+registerPradCommands(program);
 // 3D model utilities (playcraft 3d <command>)
 register3DCommands(program);
 program.parse(process.argv);

package/dist/prad/check.test.js

@@ -7,12 +7,14 @@ import { explainPradPath, formatExplain } from './explain.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const mahjongSample = path.resolve(__dirname, '..', '..', '..', '..', 'docs', 'prad', 'samples', 'mahjong-gate4.atom-tree.json');
 describe('prad check', () => {
-    it('mahjong gate4 v0.2 passes with warnings for draft atoms', () => {
+    it('mahjong gate4 v0.2.1 passes with no E026 and draft warnings only', () => {
         if (!fs.existsSync(mahjongSample))
             return;
         const result = checkPradFile(mahjongSample, { gate: 4 });
         expect(result.errors).toEqual([]);
         expect(result.warnings.some((w) => w.code === 'PRAD-W020')).toBe(true);
+        expect(result.warnings.some((w) => w.code === 'PRAD-E026')).toBe(false);
+        expect(result.errors.some((e) => e.code === 'PRAD-E026')).toBe(false);
         expect(result.ok).toBe(true);
     });
     it('explain play_btn path', () => {
@@ -24,4 +26,24 @@ describe('prad check', () => {
         expect(result.slot?.spine).toBe('medium.hook.play');
         expect(formatExplain(result)).toContain('medium.hook.play');
     });
+    it('explain rule_engine itemSprites uses pick_and_match manifest', () => {
+        if (!fs.existsSync(mahjongSample))
+            return;
+        const doc = JSON.parse(fs.readFileSync(mahjongSample, 'utf-8'));
+        const result = explainPradPath(doc, 'scenes.gameplay.board_layer.rule_engine.props.itemSprites');
+        expect(result.found).toBe(true);
+        expect(result.bindAs).toBe('itemSprites');
+        expect(result.parentEffectiveAtom).toBe('pick_and_match_rules.aigameplay');
+        expect(result.manifestImportSlots).toContain('itemSprites');
+    });
+    it('explain hint_btn icon bindAs fingerTexture on tutorial_overlay', () => {
+        if (!fs.existsSync(mahjongSample))
+            return;
+        const doc = JSON.parse(fs.readFileSync(mahjongSample, 'utf-8'));
+        const result = explainPradPath(doc, 'scenes.gameplay.hud_layer.hint_btn.props.icon');
+        expect(result.found).toBe(true);
+        expect(result.bindAs).toBe('fingerTexture');
+        expect(result.parentEffectiveAtom).toBe('tutorial_overlay.aicomponent');
+        expect(result.manifestImportSlots).toContain('fingerTexture');
+    });
 });

package/dist/prad/skills-index.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveSkillsDirs } from '../atom-plan/validate-atom-plan.js';
+import { resolveSkillsDirs } from '../atom-tree/selection.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function allSkillsDirs(customDir) {
     const dirs = resolveSkillsDirs(customDir);

package/dist/remix/init-template.js

@@ -0,0 +1,80 @@
+import * as path from 'node:path';
+import { applyEnginePackToProject, bakeFullTemplate, KNOWN_ADAPTERS, readAdapterFromAtomTree, readEngineMarker, resolveCliPackageRoot, } from '../scaffold/compose.js';
+import { autoLinkSkillsFromAtomTree } from '../commands/skills.js';
+function resolveAdapter(opts) {
+    if (opts.engine) {
+        const e = opts.engine.toLowerCase();
+        if (!KNOWN_ADAPTERS.includes(e)) {
+            throw new Error(`Unknown engine "${opts.engine}". Supported: ${KNOWN_ADAPTERS.join(', ')}`);
+        }
+        return e;
+    }
+    if (opts.fromAtomTree) {
+        const fromTree = readAdapterFromAtomTree(opts.projectDir);
+        if (!fromTree) {
+            throw new Error('docs/atom-tree.json missing meta.engineDecision.adapter — run init-atom-tree or pass --engine');
+        }
+        return fromTree;
+    }
+    throw new Error('Specify --engine phaser|threejs or --from-atom-tree');
+}
+export async function initTemplateCommand(opts) {
+    const cliRoot = resolveCliPackageRoot();
+    const projectDir = path.resolve(opts.projectDir);
+    if (opts.bake && opts.allEngines) {
+        for (const adapter of KNOWN_ADAPTERS) {
+            const outDir = path.join(cliRoot, 'project-templates', adapter);
+            const result = await bakeFullTemplate({ adapter, outDir, cliRoot });
+            console.log(`✓ Baked ${adapter} → ${result.outDir}`);
+        }
+        return;
+    }
+    const adapter = resolveAdapter(opts);
+    if (opts.bake) {
+        const outDir = path.join(cliRoot, 'project-templates', adapter);
+        const result = await bakeFullTemplate({ adapter, outDir, cliRoot });
+        console.log(`✓ Baked ${adapter} template → ${result.outDir}`);
+        return;
+    }
+    const existing = readEngineMarker(projectDir);
+    if (existing && existing !== adapter && !opts.force) {
+        console.error(`Adapter mismatch: project has .playcraft-engine=${existing}, requested ${adapter}. Use --force to replace game/.`);
+        process.exit(1);
+    }
+    const result = await applyEnginePackToProject({
+        projectDir,
+        adapter,
+        force: opts.force,
+        cliRoot,
+    });
+    console.log(`\n✓ Engine template applied: ${result.adapter}`);
+    console.log(`  game/ + .playcraft-engine + docs/scaffold-manifest.md`);
+    // Fallback auto-link: ensure selected atom skills are materialized into
+    // .claude/skills/ even if the atom-tree write hook didn't run. The
+    // validate-atom-tree-selection hook normally links on every atom-tree save;
+    // this guarantees a project bootstrapped via --from-atom-tree is never left
+    // with selected-but-unlinked atoms.
+    if (opts.fromAtomTree) {
+        try {
+            const link = await autoLinkSkillsFromAtomTree(projectDir, { prune: true });
+            if (link.linked.length > 0) {
+                console.log(`  .claude/skills/ ← linked atom skills (${link.linked.length}): ${link.linked.join(', ')}`);
+            }
+            if (link.missing.length > 0) {
+                console.log(`  ⚠ skills not found for: ${link.missing.join(', ')} — check meta.selectedAtoms`);
+            }
+        }
+        catch (err) {
+            console.log(`  ⚠ auto-link skipped: ${err.message}`);
+        }
+    }
+    console.log('\n下一步：');
+    console.log('  npm install');
+    console.log('  阅读 .claude/skills/<atom>/SKILL.md（已自动 link）并填 logs/developer-log.md § Skill Preflight');
+    console.log('  npm run placeholder:gen   # 生成占位图（Ring 1 起强制，禁止纯代码绘制）');
+    console.log('  npm run verify:contract');
+    console.log('  npm run verify:placeholders');
+    console.log('  npm run harness:smoke');
+    console.log('  → Invoke @developer for ring 1 build');
+    console.log('');
+}

package/dist/scaffold/compose.js

@@ -0,0 +1,211 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const KNOWN_ADAPTERS = ['phaser', 'threejs'];
+const TEMPLATE_COPY_EXCLUDES = new Set([
+    '.DS_Store',
+    '.git',
+    'node_modules',
+    'dist',
+    'package-lock.json',
+    'playground',
+    'recordings',
+    'validate',
+    'game',
+]);
+function isAdapterId(value) {
+    return KNOWN_ADAPTERS.includes(value);
+}
+/** CLI package root (packages/cli). */
+export function resolveCliPackageRoot() {
+    const __filename = fileURLToPath(import.meta.url);
+    return path.resolve(path.dirname(__filename), '..', '..');
+}
+export function resolveTemplateBaseDir(cliRoot = resolveCliPackageRoot()) {
+    return path.join(cliRoot, 'project-template');
+}
+export function resolveEnginePackDir(adapter, cliRoot = resolveCliPackageRoot()) {
+    return path.join(cliRoot, 'engine-packs', adapter);
+}
+export function readEngineMarker(projectDir) {
+    const markerPath = path.join(projectDir, '.playcraft-engine');
+    if (!fs.existsSync(markerPath))
+        return null;
+    const value = fs.readFileSync(markerPath, 'utf8').trim().toLowerCase();
+    return isAdapterId(value) ? value : null;
+}
+const SCAFFOLD_PENDING_FILE = '.playcraft-scaffold-pending';
+const SCAFFOLD_MANIFEST_MARKER = 'playcraft remix init-template';
+function listGameEntries(gameDir) {
+    if (!fs.existsSync(gameDir))
+        return [];
+    return fs.readdirSync(gameDir).filter((e) => e !== '.DS_Store');
+}
+/** True when game/ is missing or still the pre-scaffold placeholder from `playcraft create`. */
+export function isGameDirEmptyOrPending(gameDir) {
+    const entries = listGameEntries(gameDir);
+    if (entries.length === 0)
+        return true;
+    if (entries.includes(SCAFFOLD_PENDING_FILE)) {
+        const rest = entries.filter((e) => e !== SCAFFOLD_PENDING_FILE);
+        if (rest.length === 0)
+            return true;
+        if (rest.length === 1 && rest[0] === 'index.ts') {
+            const src = fs.readFileSync(path.join(gameDir, 'index.ts'), 'utf8');
+            return src.includes('Engine not scaffolded') || src.includes('init-template');
+        }
+    }
+    return false;
+}
+export function hasInitTemplateScaffoldManifest(projectDir) {
+    const manifestPath = path.join(projectDir, 'docs', 'scaffold-manifest.md');
+    if (!fs.existsSync(manifestPath))
+        return false;
+    const content = fs.readFileSync(manifestPath, 'utf8');
+    return content.includes(SCAFFOLD_MANIFEST_MARKER);
+}
+/** Throws unless replacing game/ is explicitly allowed. */
+export function assertGameDirReplaceAllowed(projectDir, force) {
+    if (force)
+        return;
+    const gameDest = path.join(projectDir, 'game');
+    if (!fs.existsSync(gameDest))
+        return;
+    if (isGameDirEmptyOrPending(gameDest))
+        return;
+    if (hasInitTemplateScaffoldManifest(projectDir))
+        return;
+    throw new Error('game/ already contains user implementation — refusing to overwrite. Re-run with --force to replace the entire game/ tree.');
+}
+function shouldSkipTemplateEntry(name) {
+    return TEMPLATE_COPY_EXCLUDES.has(name);
+}
+async function copyDirFiltered(src, dest, skipNames) {
+    await fs.promises.mkdir(dest, { recursive: true });
+    const entries = await fs.promises.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        if (skipNames.has(entry.name))
+            continue;
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirFiltered(srcPath, destPath, skipNames);
+        }
+        else if (entry.isFile()) {
+            await fs.promises.copyFile(srcPath, destPath);
+        }
+    }
+}
+async function copyDirRecursive(src, dest) {
+    await fs.promises.mkdir(dest, { recursive: true });
+    const entries = await fs.promises.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirRecursive(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            await fs.promises.copyFile(srcPath, destPath);
+        }
+    }
+}
+function mergePackageDeps(projectDir, adapter, packDir) {
+    const pkgPath = path.join(projectDir, 'package.json');
+    const depsPath = path.join(packDir, 'package.deps.json');
+    if (!fs.existsSync(pkgPath) || !fs.existsSync(depsPath))
+        return;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const extra = JSON.parse(fs.readFileSync(depsPath, 'utf8'));
+    pkg.dependencies = { ...pkg.dependencies, ...extra.dependencies };
+    if (extra.devDependencies) {
+        pkg.devDependencies = { ...pkg.devDependencies, ...extra.devDependencies };
+    }
+    // Remove deps from other adapters when switching engines
+    for (const other of KNOWN_ADAPTERS) {
+        if (other === adapter)
+            continue;
+        const otherPack = path.join(resolveEnginePackDir(other), 'package.deps.json');
+        if (!fs.existsSync(otherPack))
+            continue;
+        const otherDeps = JSON.parse(fs.readFileSync(otherPack, 'utf8'));
+        for (const key of Object.keys(otherDeps.dependencies ?? {})) {
+            delete pkg.dependencies?.[key];
+        }
+    }
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+function writeScaffoldManifest(projectDir, adapter, mode) {
+    const manifestPath = path.join(projectDir, 'docs', 'scaffold-manifest.md');
+    const lines = [
+        '# Scaffold Manifest',
+        '',
+        `| Field | Value |`,
+        `| --- | --- |`,
+        `| adapter | ${adapter} |`,
+        `| appliedAt | ${new Date().toISOString()} |`,
+        `| mode | ${mode} |`,
+        `| runtimeContract | window.__playable |`,
+        '',
+        'Applied by `playcraft remix init-template`.',
+        '',
+    ];
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, lines.join('\n'));
+}
+/** Apply engine pack to an existing project (user/agent mode). */
+export async function applyEnginePackToProject(options) {
+    const cliRoot = options.cliRoot ?? resolveCliPackageRoot();
+    const projectDir = path.resolve(options.projectDir);
+    const adapter = options.adapter;
+    const packDir = resolveEnginePackDir(adapter, cliRoot);
+    const gameSrc = path.join(packDir, 'game');
+    const gameDest = path.join(projectDir, 'game');
+    if (!fs.existsSync(gameSrc)) {
+        throw new Error(`Engine pack missing game/: ${gameSrc}`);
+    }
+    const existing = readEngineMarker(projectDir);
+    if (existing && existing !== adapter && !options.force) {
+        throw new Error(`Adapter mismatch: .playcraft-engine=${existing} but requested ${adapter}. Use --force to replace game/.`);
+    }
+    assertGameDirReplaceAllowed(projectDir, options.force);
+    if (fs.existsSync(gameDest)) {
+        await fs.promises.rm(gameDest, { recursive: true, force: true });
+    }
+    await copyDirRecursive(gameSrc, gameDest);
+    mergePackageDeps(projectDir, adapter, packDir);
+    fs.writeFileSync(path.join(projectDir, '.playcraft-engine'), `${adapter}\n`);
+    writeScaffoldManifest(projectDir, adapter, 'apply');
+    return { adapter, outDir: projectDir, filesWritten: ['game/', '.playcraft-engine', 'docs/scaffold-manifest.md', 'package.json'] };
+}
+/** Bake full template-base ⊕ engine-pack (maintainer mode). */
+export async function bakeFullTemplate(options) {
+    const cliRoot = options.cliRoot ?? resolveCliPackageRoot();
+    const baseDir = resolveTemplateBaseDir(cliRoot);
+    const packDir = resolveEnginePackDir(options.adapter, cliRoot);
+    const outDir = path.resolve(options.outDir);
+    if (fs.existsSync(outDir)) {
+        await fs.promises.rm(outDir, { recursive: true, force: true });
+    }
+    await copyDirFiltered(baseDir, outDir, TEMPLATE_COPY_EXCLUDES);
+    await copyDirRecursive(path.join(packDir, 'game'), path.join(outDir, 'game'));
+    mergePackageDeps(outDir, options.adapter, packDir);
+    fs.writeFileSync(path.join(outDir, '.playcraft-engine'), `${options.adapter}\n`);
+    writeScaffoldManifest(outDir, options.adapter, 'bake');
+    return { adapter: options.adapter, outDir, filesWritten: ['full template tree'] };
+}
+export function readAdapterFromAtomTree(projectDir) {
+    const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+    if (!fs.existsSync(jsonPath))
+        return null;
+    try {
+        const tree = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+        const adapter = tree.meta?.engineDecision?.adapter;
+        if (typeof adapter === 'string' && isAdapterId(adapter))
+            return adapter;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/engine-packs/phaser/game/adapters/phaser.ts

@@ -0,0 +1,52 @@
+import type Phaser from "phaser";
+import {
+  assertPlayableSceneContract,
+  publishPlayableRuntime,
+  type PlayableMainSceneLike,
+  type SceneManagerContract,
+} from "../contract/publish.js";
+
+/** The MainScene shape the legacy Phaser recorder/debug harness expects. */
+export interface PlayableMainScene extends Phaser.Scene {
+  sceneManager: SceneManagerContract;
+  _onDebugAutoPlay(): void;
+}
+
+/**
+ * Publish the Phaser.Game instance for engine-specific tools.
+ * Harness entry point remains window.__playable — do not shadow Game.start().
+ */
+export function registerPlayable(game: Phaser.Game): Phaser.Game {
+  window.__game = game;
+  return game;
+}
+
+export function bindPlayableScene(
+  scene: Phaser.Scene,
+  binding: { sceneManager: SceneManagerContract; onDebugAutoPlay: () => void },
+): void {
+  const target = scene as PlayableMainScene;
+  target.sceneManager = binding.sceneManager;
+  target._onDebugAutoPlay = binding.onDebugAutoPlay;
+  if (scene.game) {
+    publishPlayableRuntime({
+      engine: "phaser",
+      engineHandle: scene.game,
+      sceneManager: binding.sceneManager,
+      onDebugAutoPlay: binding.onDebugAutoPlay,
+      getCanvas: () => scene.game?.canvas ?? null,
+      getCaptureFps: () => scene.game?.loop?.targetFps ?? 60,
+      hideDebugUi: () => {
+        const main = scene.game?.scene?.getScene("MainScene") as PlayableMainSceneLike & {
+          debugButton?: { container?: { setVisible(v: boolean): void } };
+        };
+        main?.debugButton?.container?.setVisible(false);
+      },
+    });
+  }
+  if (__DEV__) {
+    assertPlayableSceneContract(target);
+  }
+}
+
+export { assertPlayableSceneContract, publishPlayableRuntime };

package/engine-packs/phaser/game/config/game-config.ts

@@ -0,0 +1,46 @@
+/**
+ * GAME_CONFIG — single source of truth for layout + runtime switches.
+ *
+ * Both the running game (TypeScript) and the verification harness
+ * (`verify:ui` loads this file directly via esbuild) read THIS file.
+ * There is no generated copy, so the values verify against can never drift
+ * from the values the game runs with.
+ */
+
+export interface GameConfig {
+  /** Design-space canvas width in px (portrait playable). */
+  DESIGN_WIDTH: number;
+  /** Design-space canvas height in px. */
+  DESIGN_HEIGHT: number;
+
+  /** CTA band vertical center / height / width in design space. */
+  CTA_Y: number;
+  CTA_H: number;
+  CTA_W: number;
+
+  /** Safe-area insets in px. */
+  SAFE_TOP: number;
+  SAFE_BOTTOM: number;
+  SAFE_SIDE: number;
+
+  /** Dev/record switch: show the one-click auto-play debug button. */
+  SHOW_DEBUG_BUTTON: boolean;
+  /** Dev/record switch: skip transitions to speed up capture. */
+  SKIP_TRANSITIONS: boolean;
+}
+
+export const GAME_CONFIG: GameConfig = {
+  DESIGN_WIDTH: 1080,
+  DESIGN_HEIGHT: 1920,
+
+  CTA_Y: 1620,
+  CTA_H: 300,
+  CTA_W: 1080,
+
+  SAFE_TOP: 48,
+  SAFE_BOTTOM: 48,
+  SAFE_SIDE: 16,
+
+  SHOW_DEBUG_BUTTON: true,
+  SKIP_TRANSITIONS: false,
+};