@playcraft/cli 0.0.44 → 0.0.47

package/dist/prad/explain.js

@@ -0,0 +1,109 @@
+import { parseAtomRef } from './atom-ref.js';
+import { loadSpineRegistry } from './load-spec.js';
+import { resolvePath } from './paths.js';
+import { effectiveAtomId, loadManifestImports, loadRegistryAtomIds } from './skills-index.js';
+export function explainPradPath(doc, logicalPath, options = {}) {
+    const visit = resolvePath(doc, logicalPath);
+    if (!visit) {
+        return { path: logicalPath, found: false };
+    }
+    const registry = loadRegistryAtomIds(options.skillsDir);
+    const spineReg = loadSpineRegistry(options.specDir);
+    const result = { path: logicalPath, found: true, kind: visit.kind };
+    if (visit.kind === 'entity' && visit.entity) {
+        const atom = parseAtomRef(visit.entity.atom);
+        result.atom = atom ?? undefined;
+        result.effectiveAtomId = atom ? effectiveAtomId(atom) : undefined;
+        result.registryHit = atom ? registry.has(atom.id) : undefined;
+        if (atom?.resolve === 'draft' && atom.substitute) {
+            result.registryHit = registry.has(atom.substitute);
+        }
+        result.slot = visit.entity.slot;
+        result.sinceGate = visit.entity.sinceGate;
+        const spineId = visit.entity.slot?.spine;
+        if (spineId && spineReg.spines[spineId]) {
+            result.spineDescription = spineReg.spines[spineId].description;
+        }
+        const props = visit.entity.props;
+        if (props) {
+            const refs = [];
+            for (const [k, v] of Object.entries(props)) {
+                if (v && typeof v === 'object' && 'ref' in v)
+                    refs.push(`${k} → ${v.ref}`);
+                if (typeof v === 'string' && k.endsWith('Ref'))
+                    refs.push(`${k} → ${v}`);
+                if (k === 'binding' && typeof v === 'string')
+                    refs.push(`binding → ${v}`);
+            }
+            if (refs.length)
+                result.refs = refs;
+        }
+    }
+    if (visit.kind === 'media' && visit.mediaInstance) {
+        const atom = parseAtomRef(visit.mediaInstance.atom);
+        result.atom = atom ?? undefined;
+        result.effectiveAtomId = atom ? effectiveAtomId(atom) : undefined;
+        result.bindAs = visit.mediaInstance.bindAs;
+        const bindTargetRef = visit.mediaInstance.bindTargetRef;
+        if (bindTargetRef) {
+            result.bindTargetRef = bindTargetRef;
+            const targetVisit = resolvePath(doc, bindTargetRef);
+            if (targetVisit?.entity) {
+                const targetAtom = parseAtomRef(targetVisit.entity.atom);
+                if (targetAtom) {
+                    const targetEff = effectiveAtomId(targetAtom);
+                    result.bindTargetEffectiveAtom = targetEff;
+                    const imports = loadManifestImports(targetEff, options.skillsDir);
+                    if (imports)
+                        result.manifestImportSlots = [...imports.bindAsSet];
+                }
+            }
+        }
+        else if (visit.parentEntityAtom) {
+            const parentEff = effectiveAtomId(visit.parentEntityAtom);
+            result.parentEffectiveAtom = parentEff;
+            const imports = loadManifestImports(parentEff, options.skillsDir);
+            if (imports)
+                result.manifestImportSlots = [...imports.bindAsSet];
+        }
+    }
+    if (visit.kind === 'global' && visit.mediaInstance) {
+        result.atom = parseAtomRef(visit.mediaInstance.atom) ?? undefined;
+        result.bindAs = visit.mediaInstance.bindAs;
+    }
+    return result;
+}
+export function formatExplain(result) {
+    const lines = [`path: ${result.path}`, `found: ${result.found}`];
+    if (!result.found)
+        return lines.join('\n');
+    if (result.kind)
+        lines.push(`kind: ${result.kind}`);
+    if (result.slot)
+        lines.push(`slot: ${JSON.stringify(result.slot)}`);
+    if (result.sinceGate != null)
+        lines.push(`sinceGate: ${result.sinceGate}`);
+    if (result.atom)
+        lines.push(`atom: ${JSON.stringify(result.atom)}`);
+    if (result.effectiveAtomId)
+        lines.push(`effectiveAtomId: ${result.effectiveAtomId}`);
+    if (result.registryHit != null)
+        lines.push(`registryHit: ${result.registryHit}`);
+    if (result.spineDescription) {
+        lines.push(`spineDescription: ${result.spineDescription.zh ?? result.spineDescription.en ?? ''}`);
+    }
+    if (result.bindAs)
+        lines.push(`bindAs: ${result.bindAs}`);
+    if (result.bindTargetRef)
+        lines.push(`bindTargetRef: ${result.bindTargetRef}`);
+    if (result.parentEffectiveAtom)
+        lines.push(`parentEffectiveAtom: ${result.parentEffectiveAtom}`);
+    if (result.bindTargetEffectiveAtom)
+        lines.push(`bindTargetEffectiveAtom: ${result.bindTargetEffectiveAtom}`);
+    if (result.manifestImportSlots?.length) {
+        lines.push(`manifestImportSlots: ${result.manifestImportSlots.join(', ')}`);
+    }
+    if (result.refs?.length)
+        lines.push(`refs:\n  ${result.refs.join('\n  ')}`);
+    return lines.join('\n');
+}

package/dist/prad/load-spec.js

@@ -0,0 +1,23 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export function resolvePradSpecDir(customDir) {
+    if (customDir)
+        return path.resolve(customDir);
+    const mono = path.resolve(__dirname, '..', '..', '..', '..', 'docs', 'prad', 'spec');
+    if (fs.existsSync(path.join(mono, 'spine-registry.v1.json')))
+        return mono;
+    const cwd = path.join(process.cwd(), 'docs', 'prad', 'spec');
+    if (fs.existsSync(path.join(cwd, 'spine-registry.v1.json')))
+        return cwd;
+    return mono;
+}
+export function loadSpineRegistry(specDir) {
+    const file = path.join(resolvePradSpecDir(specDir), 'spine-registry.v1.json');
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+export function loadGateRequirements(specDir) {
+    const file = path.join(resolvePradSpecDir(specDir), 'gate-requirements.v1.json');
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}

package/dist/prad/paths.js

@@ -0,0 +1,83 @@
+import { parseAtomRef } from './atom-ref.js';
+function visitEntities(basePath, entities, out, parentEntityAtom) {
+    if (!Array.isArray(entities))
+        return;
+    for (const raw of entities) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const entity = raw;
+        const id = entity.id;
+        if (typeof id !== 'string')
+            continue;
+        const entityPath = `${basePath}.${id}`;
+        const atomRef = parseAtomRef(entity.atom);
+        out.push({ path: entityPath, kind: 'entity', entity, parentEntityAtom });
+        const props = entity.props;
+        if (props && typeof props === 'object') {
+            for (const [key, val] of Object.entries(props)) {
+                if (val && typeof val === 'object' && 'atom' in val) {
+                    out.push({
+                        path: `${entityPath}.props.${key}`,
+                        kind: 'media',
+                        entity,
+                        parentEntityAtom: atomRef ?? undefined,
+                        mediaPropKey: key,
+                        mediaInstance: val,
+                    });
+                }
+            }
+        }
+        if (Array.isArray(entity.children)) {
+            visitEntities(entityPath, entity.children, out, atomRef ?? undefined);
+        }
+    }
+}
+export function walkPradDocument(doc) {
+    const out = [];
+    const globals = doc.globals;
+    if (globals && typeof globals === 'object') {
+        for (const [key, val] of Object.entries(globals)) {
+            if (val && typeof val === 'object' && 'atom' in val) {
+                out.push({
+                    path: `globals.${key}`,
+                    kind: 'global',
+                    globalKey: key,
+                    mediaInstance: val,
+                });
+            }
+        }
+    }
+    const scenes = doc.scenes;
+    if (Array.isArray(scenes)) {
+        for (const scene of scenes) {
+            if (!scene || typeof scene !== 'object')
+                continue;
+            const sceneId = scene.id;
+            if (typeof sceneId !== 'string')
+                continue;
+            const layers = scene.layers;
+            if (!Array.isArray(layers))
+                continue;
+            for (const layer of layers) {
+                if (!layer || typeof layer !== 'object')
+                    continue;
+                const layerId = layer.id;
+                if (typeof layerId !== 'string')
+                    continue;
+                const base = `scenes.${sceneId}.${layerId}`;
+                visitEntities(base, layer.entities ?? [], out);
+            }
+        }
+    }
+    return out;
+}
+export function resolvePath(doc, logicalPath) {
+    return walkPradDocument(doc).find((v) => v.path === logicalPath);
+}
+/** Media path `scenes.x.y.z.props.key` → entity path `scenes.x.y.z` */
+export function parentEntityPath(mediaPath) {
+    const idx = mediaPath.lastIndexOf('.props.');
+    if (idx === -1)
+        return undefined;
+    return mediaPath.slice(0, idx);
+}

package/dist/prad/skills-index.js

@@ -0,0 +1,60 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveSkillsDirs } from '../atom-tree/selection.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function allSkillsDirs(customDir) {
+    const dirs = resolveSkillsDirs(customDir);
+    const monoFromPrad = path.resolve(__dirname, '..', '..', '..', 'skills', 'skills');
+    if (fs.existsSync(monoFromPrad))
+        dirs.push(monoFromPrad);
+    return [...new Set(dirs)];
+}
+/** Load set of registry atom ids from Skills directories. */
+export function loadRegistryAtomIds(skillsDir) {
+    const ids = new Set();
+    for (const dir of allSkillsDirs(skillsDir)) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const name of fs.readdirSync(dir)) {
+            const manifestPath = path.join(dir, name, 'manifest.json');
+            if (!fs.existsSync(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (manifest.atomId)
+                    ids.add(manifest.atomId);
+            }
+            catch {
+                // skip invalid manifest
+            }
+        }
+    }
+    return ids;
+}
+export function loadManifestImports(atomId, skillsDir) {
+    for (const dir of allSkillsDirs(skillsDir)) {
+        const manifestPath = path.join(dir, atomId, 'manifest.json');
+        if (!fs.existsSync(manifestPath))
+            continue;
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            const bindAsSet = new Set();
+            for (const imp of manifest.imports ?? []) {
+                if (imp.bindAs)
+                    bindAsSet.add(imp.bindAs);
+            }
+            return { atomId: manifest.atomId ?? atomId, bindAsSet };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** Effective atom id for compile: draft uses substitute when present. */
+export function effectiveAtomId(ref) {
+    if (ref.resolve === 'draft' && ref.substitute)
+        return ref.substitute;
+    return ref.id;
+}

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,
+};