@playcraft/cli 0.1.82 → 0.1.84-beta

package/dist/commands/references.js

@@ -16,7 +16,8 @@ export function registerReferenceCommands(program) {
                     ...(options.tag?.length ? { tagCategory: options.tagCategory ?? 'Gameplay', tagValues: options.tag }
                         : options.tagCategory === undefined ? {} : { tagCategory: options.tagCategory }),
                     page: Number(options.page), limit: Number(options.limit) } : {}),
-                ...(action === 'import' ? { projectUuid: options.project, branchName: options.branch } : {}) });
+                ...(action === 'import' ? { projectUuid: options.project, branchName: options.branch } : {}),
+                ...(action === 'prepare-starter-template' ? { templateId: options.template } : {}) });
             const output = { schemaVersion: 'playcraft.references.v1', command: `references.${action}`, ...result };
             if (options.json)
                 console.log(JSON.stringify(output));
@@ -45,7 +46,8 @@ export function registerReferenceCommands(program) {
     const scope = (command) => command.option('--workspace <id>', message('workspace'))
         .option('--directory <name>', message('directory')).option('--json', message('json'));
     scope(references.command('list').description(message('list'))).action(options => run('list', options));
-    scope(references.command('prepare-starter-template').description(message('prepareStarterTemplate'))).action(options => run('prepare-starter-template', options));
+    scope(references.command('prepare-starter-template').description(message('prepareStarterTemplate'))
+        .option('--template <id>', message('template'))).action(options => run('prepare-starter-template', options));
     scope(references.command('search [query]').description(message('search'))
         .option('--source <source>', message('source'), 'recommended')
         .option('--tag <value>', message('tag'), (value, previous) => [...previous, value], [])

package/dist/commands/tools-generation.js

@@ -3,8 +3,8 @@ import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
 import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
-import { resolveImageBackgroundRequirement, validateImageDeliveryOptions } from '@playcraft/common/prefab';
-import { assertImageAssetOutputPaths, readImageAssetContext } from '../utils/image-asset-context.js';
+import { resolveImageBackgroundRequirement, validateImageDeliveryOptions, } from '@playcraft/common/prefab';
+import { assertImageAssetOutputPaths, readImageAssetContext, } from '../utils/image-asset-context.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { isUnsafeImageRetryError } from '../utils/image-generation-retry.js';
 import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, parseImageTargetFieldPath, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
@@ -73,7 +73,8 @@ async function verifyMasterCompositeStripSize(imgBuf, target) {
 }
 export function registerGenerationCommands(tools) {
     // ─── Image Models ────────────────────────────────────────────
-    tools.command('list-image-models')
+    tools
+        .command('list-image-models')
         .description('列出后端已配置的可用生图模型，按模型名分组展示所有 provider（多个 provider 时按优先级自动 fallback）')
         .option('--json', '以 JSON 格式输出（默认为人类可读表格）')
         .action(async (opts) => {
@@ -150,7 +151,8 @@ export function registerGenerationCommands(tools) {
         }
     });
     // ─── Generation ─────────────────────────────────────────────
-    tools.command('generate-image')
+    tools
+        .command('generate-image')
         .description('AI 生成图片（支持多张参考图图生图；gpt-image-2 支持 --count N 批量出图）')
         .requiredOption('--prompt <text>', '图片描述')
         .option('--aspect-ratio <ratio>', '宽高比 (1:1|45:16|16:9|9:16|3:4|4:3|2:3|3:2|21:9)', '1:1')
@@ -174,8 +176,12 @@ export function registerGenerationCommands(tools) {
         .option('--count <n>', '一次 API 调用生成多少张图片（默认 1，最多 10；仅 gpt-image-2 实际支持批量）', (v) => parseInt(v, 10), 1)
         .action(async (opts) => {
         try {
-            const explicitBackground = opts.background === undefined ? opts.removeBackground : opts.background === 'transparent';
-            if (opts.background !== undefined && opts.removeBackground !== undefined && opts.removeBackground !== explicitBackground) {
+            const explicitBackground = opts.background === undefined
+                ? opts.removeBackground
+                : opts.background === 'transparent';
+            if (opts.background !== undefined &&
+                opts.removeBackground !== undefined &&
+                opts.removeBackground !== explicitBackground) {
                 throw new Error('Conflicting background options. Use --background transparent or --background opaque; no image request was sent.');
             }
             opts = { ...opts, removeBackground: explicitBackground };
@@ -184,28 +190,46 @@ export function registerGenerationCommands(tools) {
             }
             const explicitOutputFormat = opts.outputFormat;
             const { dir: outputDir, name: outputName, ext: outputExt } = parse(opts.output);
-            const outputCandidates = [opts.output, ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`))];
-            const assetContext = opts.targetAsset ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
-                referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
-                ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
-                outputPaths: outputCandidates,
-                prompt: opts.prompt, removeBackground: opts.removeBackground,
-            }) : undefined;
-            opts = { ...opts,
+            const outputCandidates = [
+                opts.output,
+                ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`)),
+            ];
+            const assetContext = opts.targetAsset
+                ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
+                    referenceImagePaths: opts.referenceImage,
+                    useTargetReference: opts.targetReference,
+                    ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
+                    outputPaths: outputCandidates,
+                    prompt: opts.prompt,
+                    removeBackground: opts.removeBackground,
+                })
+                : undefined;
+            opts = {
+                ...opts,
                 aspectRatio: assetContext?.aspectRatio ?? opts.aspectRatio,
-                width: assetContext?.width ?? opts.width, height: assetContext?.height ?? opts.height,
-                outputFormat: assetContext?.outputFormatFromSchema ? assetContext.outputFormat : opts.outputFormat ?? assetContext?.outputFormat,
+                width: assetContext?.width ?? opts.width,
+                height: assetContext?.height ?? opts.height,
+                outputFormat: assetContext?.outputFormatFromSchema
+                    ? assetContext.outputFormat
+                    : (opts.outputFormat ?? assetContext?.outputFormat),
                 fitMode: assetContext?.fitMode ?? opts.fitMode,
-                removeBackground: resolveImageBackgroundRequirement({ prompt: opts.prompt,
-                    schemaRemoveBackground: assetContext?.removeBackgroundFromSchema ? assetContext.removeBackground : undefined,
-                    removeBackground: opts.removeBackground, fallbackRemoveBackground: assetContext?.removeBackground }),
+                removeBackground: resolveImageBackgroundRequirement({
+                    prompt: opts.prompt,
+                    schemaRemoveBackground: assetContext?.removeBackgroundFromSchema
+                        ? assetContext.removeBackground
+                        : undefined,
+                    removeBackground: opts.removeBackground,
+                    fallbackRemoveBackground: assetContext?.removeBackground,
+                }),
                 paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
                 imageModel: opts.imageModel || assetContext?.imageModelRef,
             };
             const invalidDelivery = validateImageDeliveryOptions(opts);
             if (invalidDelivery)
                 throw new Error(invalidDelivery);
-            const paths = opts.referenceImage?.length ? opts.referenceImage : assetContext?.referenceImagePaths ?? [];
+            const paths = opts.referenceImage?.length
+                ? opts.referenceImage
+                : (assetContext?.referenceImagePaths ?? []);
             if (paths.length > MAX_REFERENCE_IMAGES) {
                 console.error(`Error: Too many reference images: ${paths.length} paths given; maximum is ${MAX_REFERENCE_IMAGES}.`);
                 process.exit(1);
@@ -230,14 +254,26 @@ export function registerGenerationCommands(tools) {
                     width: assetContext?.width ?? opts.width,
                     height: assetContext?.height ?? opts.height,
                     outputFormat: opts.outputFormat,
-                    outputFormatSource: assetContext?.outputFormatFromSchema ? 'schema'
-                        : explicitOutputFormat ? 'explicit' : assetContext ? 'inferred' : undefined,
+                    outputFormatSource: assetContext?.outputFormatFromSchema
+                        ? 'schema'
+                        : explicitOutputFormat
+                            ? 'explicit'
+                            : assetContext
+                                ? 'inferred'
+                                : undefined,
                     fitMode: assetContext?.fitMode ?? opts.fitMode,
                     paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
-                    background: opts.background === undefined ? undefined : opts.removeBackground ? 'transparent' : 'opaque',
+                    background: opts.background === undefined
+                        ? undefined
+                        : opts.removeBackground
+                            ? 'transparent'
+                            : 'opaque',
                     removeBackground: opts.removeBackground,
-                    backgroundRequirementSource: assetContext?.removeBackgroundFromSchema ? 'schema'
-                        : explicitBackground !== undefined ? 'explicit' : 'inferred',
+                    backgroundRequirementSource: assetContext?.removeBackgroundFromSchema
+                        ? 'schema'
+                        : explicitBackground !== undefined
+                            ? 'explicit'
+                            : 'inferred',
                     referenceImages,
                     ...(modelRef ? { imageModelRef: modelRef } : {}),
                     ...(imageCount > 1 ? { imageCount } : {}),
@@ -265,7 +301,8 @@ export function registerGenerationCommands(tools) {
                     lines.push('  → Try --image-size 1K to reduce generation time');
                     lines.push('  → Or increase timeout with --timeout <seconds> (current default: 1800s)');
                 }
-                else if (hasReferenceImages && (msg.includes('reference') || msg.includes('image input'))) {
+                else if (hasReferenceImages &&
+                    (msg.includes('reference') || msg.includes('image input'))) {
                     lines.push('');
                     lines.push('Hint: Reference image error — the selected model may not support --reference-image.');
                     lines.push('  → Run: playcraft tools list-image-models');
@@ -313,7 +350,11 @@ export function registerGenerationCommands(tools) {
             }
             // 收集所有待保存图片（第 1 张 + 批量额外图）
             const allImages = [
-                { imageBase64: result.imageBase64, mimeType: result.mimeType, previewUrl: result.previewUrl },
+                {
+                    imageBase64: result.imageBase64,
+                    mimeType: result.mimeType,
+                    previewUrl: result.previewUrl,
+                },
                 ...(result.additionalImages ?? []),
             ];
             const isBatch = allImages.length > 1;
@@ -324,12 +365,14 @@ export function registerGenerationCommands(tools) {
             const savedPaths = [];
             if (result.transparencySource)
                 console.log(`Transparency source: ${result.transparencySource}`);
-            const stripTarget = opts.targetAsset || result.transparentBackground ? null : resolveStripTargetDimensions({
-                aspectRatio: opts.aspectRatio,
-                width: opts.width,
-                height: opts.height,
-                imageSize: opts.imageSize,
-            });
+            const stripTarget = opts.targetAsset || result.transparentBackground
+                ? null
+                : resolveStripTargetDimensions({
+                    aspectRatio: opts.aspectRatio,
+                    width: opts.width,
+                    height: opts.height,
+                    imageSize: opts.imageSize,
+                });
             for (let i = 0; i < allImages.length; i++) {
                 const img = allImages[i];
                 let imgBuf = Buffer.from(img.imageBase64, 'base64');
@@ -347,8 +390,7 @@ export function registerGenerationCommands(tools) {
                     generatedHeight = metaBefore.height;
                     if (metaBefore.width != null &&
                         metaBefore.height != null &&
-                        (metaBefore.width !== stripTarget.width ||
-                            metaBefore.height !== stripTarget.height)) {
+                        (metaBefore.width !== stripTarget.width || metaBefore.height !== stripTarget.height)) {
                         imgBuf = Buffer.from(await letterboxToTarget(imgBuf, stripTarget.width, stripTarget.height));
                         console.log(`↑ Letterbox ${generatedWidth}×${generatedHeight} → ${stripTarget.width}×${stripTarget.height}（等比 + 白边，不拉伸）`);
                     }
@@ -404,10 +446,11 @@ export function registerGenerationCommands(tools) {
                     referenceImageStatus: result.referenceImageStatus ?? null,
                     generatedAt: new Date().toISOString(),
                 };
-                const sidecarPath = resolvedPath.replace(/\.[^.]+$/, '.json');
+                const sidecarPath = `${resolvedPath}.generation.json`;
                 writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2));
                 await captureGeneratedArtifact(resolvedPath, 'generate-image', {
-                    ...(actualWidth ? { width: actualWidth } : {}), ...(actualHeight ? { height: actualHeight } : {}),
+                    ...(actualWidth ? { width: actualWidth } : {}),
+                    ...(actualHeight ? { height: actualHeight } : {}),
                 });
                 console.log(`  └─ Generation metadata: ${sidecarPath}`);
             }
@@ -431,7 +474,8 @@ export function registerGenerationCommands(tools) {
             handleError(e);
         }
     });
-    tools.command('generate-sfx')
+    tools
+        .command('generate-sfx')
         .description('AI 生成音效（SFX），使用 ElevenLabs Sound Effects')
         .requiredOption('--prompt <text>', '音效描述，仅英文，如 "crisp UI click, short tail, no voice"')
         .option('--duration <seconds>', '时长（秒，0.5-22；省略时由供应商自动决定）', parseFloat)
@@ -451,9 +495,14 @@ export function registerGenerationCommands(tools) {
             const sizeKB = Math.round(buf.length / 1024);
             console.log(`SFX saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
             const sfxSidecar = {
-                type: 'sfx', prompt: opts.prompt, duration: opts.duration ?? null,
-                loop: opts.loop ?? false, provider: result.provider, actualDuration: result.duration,
-                output: opts.output, generatedAt: new Date().toISOString(),
+                type: 'sfx',
+                prompt: opts.prompt,
+                duration: opts.duration ?? null,
+                loop: opts.loop ?? false,
+                provider: result.provider,
+                actualDuration: result.duration,
+                output: opts.output,
+                generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(sfxSidecar, null, 2));
             await captureGeneratedArtifact(opts.output, 'generate-sfx', { duration: result.duration });
@@ -463,7 +512,8 @@ export function registerGenerationCommands(tools) {
             handleError(e);
         }
     });
-    tools.command('generate-bgm')
+    tools
+        .command('generate-bgm')
         .description('AI 生成 BGM（30s 循环），使用 Google Lyria 3')
         .requiredOption('--prompt <text>', 'BGM 描述，如 "轻快休闲游戏配乐"')
         .option('--style <style>', '音乐风格，如 casual / epic / sci-fi / retro')
@@ -484,9 +534,14 @@ export function registerGenerationCommands(tools) {
             const sizeKB = Math.round(buf.length / 1024);
             console.log(`BGM saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
             const bgmSidecar = {
-                type: 'bgm', prompt: opts.prompt, style: opts.style ?? null,
-                bpm: opts.bpm ?? null, provider: result.provider, actualDuration: result.duration,
-                output: opts.output, generatedAt: new Date().toISOString(),
+                type: 'bgm',
+                prompt: opts.prompt,
+                style: opts.style ?? null,
+                bpm: opts.bpm ?? null,
+                provider: result.provider,
+                actualDuration: result.duration,
+                output: opts.output,
+                generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(bgmSidecar, null, 2));
             await captureGeneratedArtifact(opts.output, 'generate-bgm', { duration: result.duration });
@@ -517,7 +572,8 @@ export function registerGenerationCommands(tools) {
         }
     });
     // ─── Search Image ──────────────────────────────────────────
-    tools.command('search-image')
+    tools
+        .command('search-image')
         .description('搜索参考图片（Unsplash / Pexels），结果 URL 可直接用于 --reference-image')
         .requiredOption('--query <query>', '搜索关键词（建议英文）')
         .option('--source <source>', '图源：unsplash | pexels | auto（默认 auto）', 'auto')

package/dist/commands/tools-utils.js

@@ -1,5 +1,5 @@
 import { writeFileSync, mkdirSync, readFileSync } from 'fs';
-import { join, parse } from 'path';
+import { join, parse, resolve } from 'path';
 import { tmpdir } from 'os';
 import { InvalidArgumentError } from 'commander';
 export const TMP_DIR = join(tmpdir(), 'playcraft');
@@ -9,8 +9,12 @@ export function parseImageTargetFieldPath(value) {
     try {
         parsed = JSON.parse(value);
     }
-    catch { /* Report the expected shape below. */ }
-    if (!Array.isArray(parsed) || !parsed.length || parsed.some(key => typeof key !== 'string' || !key.length)) {
+    catch {
+        /* Report the expected shape below. */
+    }
+    if (!Array.isArray(parsed) ||
+        !parsed.length ||
+        parsed.some((key) => typeof key !== 'string' || !key.length)) {
         throw new InvalidArgumentError('Expected an array of field names, e.g. ["endUI","playButton"].');
     }
     return parsed;
@@ -74,11 +78,7 @@ export function extensionForImageMime(mimeType) {
  * Detect container from decoded bytes (magic). Prefer this over MIME alone.
  */
 export function sniffImageExtension(buf) {
-    if (buf.length >= 8 &&
-        buf[0] === 0x89 &&
-        buf[1] === 0x50 &&
-        buf[2] === 0x4e &&
-        buf[3] === 0x47) {
+    if (buf.length >= 8 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
         return '.png';
     }
     if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
@@ -133,12 +133,14 @@ export function mimeTypeForImagePath(filePath) {
         return 'image/png';
     if (ext === 'webp')
         return 'image/webp';
+    if (ext === 'gif')
+        return 'image/gif';
     if (ext === 'jpg' || ext === 'jpeg')
         return 'image/jpeg';
     if (ext === undefined || ext === '') {
         throw new Error(`Reference image path has no file extension: ${filePath}. Use .png, .webp, .jpg, or .jpeg.`);
     }
-    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, and jpeg are allowed.`);
+    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, jpeg, and gif are allowed.`);
 }
 async function downloadImageFromUrl(url) {
     let res;
@@ -155,7 +157,8 @@ async function downloadImageFromUrl(url) {
     const contentType = res.headers.get('content-type') ?? '';
     const mimeType = contentType.split(';')[0].trim() || 'image/png';
     const allowed = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'];
-    if (!allowed.some((t) => mimeType.startsWith(t.split('/')[0]) && mimeType.includes('/')) || !mimeType.startsWith('image/')) {
+    if (!allowed.some((t) => mimeType.startsWith(t.split('/')[0]) && mimeType.includes('/')) ||
+        !mimeType.startsWith('image/')) {
         throw new Error(`参考图 URL 返回的 Content-Type 不是图片（${mimeType}）：${url}\n  只支持 PNG / JPG / WEBP / GIF。`);
     }
     const buf = await res.arrayBuffer();
@@ -178,18 +181,13 @@ export async function collectReferenceImagePayloads(paths) {
             }
             else {
                 const mimeType = mimeTypeForImagePath(p);
-                out.push({ base64: readFileSync(p).toString('base64'), mimeType });
+                out.push({ base64: readFileSync(resolve(process.cwd(), p)).toString('base64'), mimeType });
             }
         }
         catch (e) {
             const detail = e instanceof Error ? e.message : String(e);
-            const code = !isUrl && e && typeof e === 'object' && 'code' in e ? String(e.code) : '';
-            const hint = code ? ` (${code})` : '';
-            console.warn(`Skipping reference image (load failed): ${p}${hint}\n  ${detail}`);
+            throw new Error(`Could not load reference image "${p}": ${detail}. No image request was sent.`);
         }
     }
-    if (paths.length > 0 && out.length === 0) {
-        console.warn('All reference images failed to load; continuing with text-only generation.');
-    }
     return out.length > 0 ? out : undefined;
 }

package/dist/references/messages.js

@@ -4,6 +4,7 @@ const messages = {
         list: 'List verified local Remix references and their paths', search: 'Search accessible recommended or community Remixes',
         import: 'Import a fixed Remix source snapshot into the current engineering directory',
         prepareStarterTemplate: 'Prepare a verified starter template in a temporary directory',
+        template: 'Starter template: cocos (default) or threejs',
         query: 'Search names, branches, tags, creators or templates', source: 'recommended or community', project: 'Source project identifier', branch: 'Exact source branch',
         tag: 'Match a tag value; repeat to match any of the values', tagCategory: 'Tag category; defaults to Gameplay when --tag is used',
         workspace: 'Current cloud workspace identifier (must match this conversation)', directory: 'Current engineering directory (must match this conversation)',
@@ -24,6 +25,7 @@ const messages = {
         description: '为当前云工作区发现并导入 Remix 源码参考',
         list: '列出已验证的本地 Remix 参考及路径', search: '搜索可访问的推荐或社区 Remix', import: '把固定版本的 Remix 源码参考导入当前工程',
         prepareStarterTemplate: '将经过校验的起始模板准备到临时目录',
+        template: '起始模板：cocos（默认）或 threejs',
         query: '搜索名称、分支、标签、创建者或模板', source: 'recommended（推荐）或 community（社区）', project: '来源项目标识', branch: '准确的来源分支名',
         tag: '匹配的标签值；可重复指定，匹配任意一个值', tagCategory: '标签分类；使用 --tag 时默认为 Gameplay',
         workspace: '当前云工作区标识（必须与本对话一致）', directory: '当前工程目录（必须与本对话一致）',

package/dist/references/protocol.js

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { z } from 'zod';
+import { WORKSPACE_STARTER_TEMPLATE_IDS } from '@playcraft/common/cloud-workspace/runtime';
 const scope = {
     cwd: z.string().min(1).max(4096),
     workspaceId: z.string().uuid().optional(),
@@ -11,7 +12,9 @@ const scope = {
 export const remixReferenceToolRequestSchema = z
     .discriminatedUnion('action', [
     z.object({ ...scope, action: z.literal('list') }).strict(),
-    z.object({ ...scope, action: z.literal('prepare-starter-template') }).strict(),
+    z
+        .object({ ...scope, action: z.literal('prepare-starter-template'), templateId: z.enum(WORKSPACE_STARTER_TEMPLATE_IDS).optional() })
+        .strict(),
     z
         .object({
         ...scope,

package/dist/utils/image-asset-context.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import JSON5 from 'json5';
 import sharp from 'sharp';
-import { extractAssetFields, getByPath, resolveAiImageTargetConstraints, resolveImageBackgroundRequirement, THEME_SCHEMA_PATH, themeDataPath, } from '@playcraft/common/prefab';
+import { extractAssetFields, getByPath, parseThemeIndexImportPath, resolveAiImageTargetConstraints, resolveImageBackgroundRequirement, THEME_INDEX_PATH, THEME_SCHEMA_PATH, themeDataPath, } from '@playcraft/common/prefab';
 function isWithinDirectory(root, file) {
     const relative = path.relative(root, file);
     return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
@@ -38,20 +38,29 @@ export function assertImageAssetOutputPaths(context, outputPaths, projectDir = p
     const root = path.resolve(projectDir);
     const target = canonicalProjectPath(root, context.targetAssetPath);
     const targetStat = statSync(target);
-    const outputRoots = [root, ...allowedOutputRoots.map(outputRoot => path.resolve(root, outputRoot))];
+    const outputRoots = [
+        root,
+        ...allowedOutputRoots.map((outputRoot) => path.resolve(root, outputRoot)),
+    ];
     for (const output of outputPaths) {
         const mapped = output.startsWith('/project/') ? output.slice('/project/'.length) : output;
         const { dir, name } = path.parse(mapped);
         // The response encoding can change the requested extension.
-        const candidates = [mapped, ...['.png', '.webp', '.jpg', '.gif', '.bmp'].map(ext => path.join(dir, `${name}${ext}`))];
+        const candidates = [
+            mapped,
+            ...['.png', '.webp', '.jpg', '.gif', '.bmp'].map((ext) => path.join(dir, `${name}${ext}`)),
+        ];
         for (const candidate of candidates) {
             const candidatePath = path.resolve(root, candidate);
-            const outputRoot = outputRoots.find(allowed => isWithinDirectory(allowed, candidatePath));
+            const outputRoot = outputRoots.find((allowed) => isWithinDirectory(allowed, candidatePath));
             if (!outputRoot)
                 throw new Error(`Image output path is outside the project and allowed output roots: ${output}`);
             const file = canonicalProjectPath(outputRoot, candidatePath);
             const fileStat = existsSync(file) ? statSync(file) : undefined;
-            if (!path.relative(target, file) || (targetStat.ino !== 0 && fileStat?.ino === targetStat.ino && fileStat.dev === targetStat.dev)) {
+            if (!path.relative(target, file) ||
+                (targetStat.ino !== 0 &&
+                    fileStat?.ino === targetStat.ino &&
+                    fileStat.dev === targetStat.dev)) {
                 throw new Error(`Cannot overwrite shared image asset ${context.targetAssetPath}: other fields have different requirements. Use a separate outputPath, then explicitly update the selected field reference; no shared asset was changed.`);
             }
         }
@@ -71,8 +80,10 @@ function projectFile(root, input) {
 /** Read the same per-field constraints used by the asset image dialog. */
 export async function readImageAssetContext(assetPath, projectDir = process.cwd(), options = {}) {
     const targetFieldPath = options.targetFieldPath;
-    if (targetFieldPath !== undefined && (!Array.isArray(targetFieldPath)
-        || !targetFieldPath.length || targetFieldPath.some(key => typeof key !== 'string' || !key.length))) {
+    if (targetFieldPath !== undefined &&
+        (!Array.isArray(targetFieldPath) ||
+            !targetFieldPath.length ||
+            targetFieldPath.some((key) => typeof key !== 'string' || !key.length))) {
         throw new Error('targetFieldPath must be a non-empty array of non-empty field names.');
     }
     const root = path.resolve(projectDir);
@@ -81,24 +92,36 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
     const targetStat = statSync(target);
     const relativeTarget = path.relative(root, target).replace(/\\/g, '/');
     const themeMatch = relativeTarget.match(/^src\/theme\/([^/]+)\/assets\//);
+    const indexFile = path.join(root, THEME_INDEX_PATH);
+    const themeId = themeMatch?.[1] ??
+        (existsSync(indexFile)
+            ? parseThemeIndexImportPath(readFileSync(projectFile(root, THEME_INDEX_PATH), 'utf8'))
+            : null);
     let fields = [];
     const schemaFile = path.join(root, THEME_SCHEMA_PATH);
-    if (themeMatch && existsSync(schemaFile)) {
+    if (themeId && existsSync(schemaFile)) {
         const schema = JSON5.parse(readFileSync(projectFile(root, THEME_SCHEMA_PATH), 'utf8'));
-        const dataPath = themeDataPath(themeMatch[1]);
+        const dataPath = themeDataPath(themeId);
         const data = existsSync(path.join(root, dataPath))
-            ? JSON5.parse(readFileSync(projectFile(root, dataPath), 'utf8')) : {};
+            ? JSON5.parse(readFileSync(projectFile(root, dataPath), 'utf8'))
+            : {};
         const themeRoot = path.dirname(path.join(root, dataPath));
-        const matches = extractAssetFields(schema, data).filter(candidate => {
+        const matches = extractAssetFields(schema, data).filter((candidate) => {
             let configured = getByPath(data, candidate.path);
             if (configured === undefined && ['gameplay', 'gamePlay'].includes(candidate.path[0])) {
-                configured = getByPath(data, [candidate.path[0] === 'gameplay' ? 'gamePlay' : 'gameplay', ...candidate.path.slice(1)]);
+                configured = getByPath(data, [
+                    candidate.path[0] === 'gameplay' ? 'gamePlay' : 'gameplay',
+                    ...candidate.path.slice(1),
+                ]);
             }
             const value = typeof configured === 'string' ? configured : candidate.schema.default;
             if (typeof value !== 'string' || /^https?:\/\//i.test(value))
                 return false;
-            const configuredPath = value.startsWith('/project/') ? path.resolve(root, value.slice('/project/'.length))
-                : path.resolve(themeRoot, value);
+            const configuredPath = value.startsWith('/project/')
+                ? path.resolve(root, value.slice('/project/'.length))
+                : /^\/?src\//.test(value)
+                    ? path.resolve(root, value.replace(/^\//, ''))
+                    : path.resolve(themeRoot, value);
             if (configuredPath === target)
                 return true;
             try {
@@ -106,19 +129,22 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
                 if (!path.relative(realTarget, realpathSync(candidateFile)))
                     return true;
                 const candidateStat = statSync(candidateFile);
-                return targetStat.ino !== 0 && candidateStat.ino === targetStat.ino && candidateStat.dev === targetStat.dev;
+                return (targetStat.ino !== 0 &&
+                    candidateStat.ino === targetStat.ino &&
+                    candidateStat.dev === targetStat.dev);
             }
             catch {
                 // Other fields may reference missing files or paths outside this project.
                 return false;
             }
         });
-        if (!matches.length)
+        if (!matches.length && (themeMatch || targetFieldPath))
             throw new Error(`No image schema field matches ${relativeTarget}; check theme.data.json5 before generating.`);
         fields = matches;
-        if (targetFieldPath && !fields.some(candidate => candidate.path.length === targetFieldPath.length
-            && candidate.path.every((key, index) => key === targetFieldPath[index]))) {
-            throw new Error(`targetFieldPath ${JSON.stringify(targetFieldPath)} does not reference ${relativeTarget}. Matching fields: ${matches.map(candidate => JSON.stringify(candidate.path)).join(', ')}.`);
+        if (targetFieldPath &&
+            !fields.some((candidate) => candidate.path.length === targetFieldPath.length &&
+                candidate.path.every((key, index) => key === targetFieldPath[index]))) {
+            throw new Error(`targetFieldPath ${JSON.stringify(targetFieldPath)} does not reference ${relativeTarget}. Matching fields: ${matches.map((candidate) => JSON.stringify(candidate.path)).join(', ')}.`);
         }
     }
     else if (targetFieldPath) {
@@ -131,22 +157,35 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
         const ext = xp?.ext;
         // Schema references follow the dialog's root/theme conventions; explicit tool paths do not change.
         const schemaReferences = Array.isArray(ext?.reference_image)
-            ? ext.reference_image.filter(ref => typeof ref === 'string' && ref.trim()).map(ref => {
+            ? ext.reference_image
+                .filter((ref) => typeof ref === 'string' && ref.trim())
+                .map((ref) => {
                 const raw = ref.trim().replace(/\\/g, '/');
-                const normalized = raw.replace(/^\.\/+/, '').replace(/^\/+/, '').replace(/\/{2,}/g, '/');
+                const normalized = raw
+                    .replace(/^\.\/+/, '')
+                    .replace(/^\/+/, '')
+                    .replace(/\/{2,}/g, '/');
                 if (/^\/?(?:assets|src|public)\//.test(raw) || normalized.startsWith('src/'))
                     return normalized;
-                if (!themeMatch || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
+                if (!themeId || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
                     return raw;
-                return path.posix.join('src/theme', themeMatch[1], normalized);
-            }) : [];
-        const references = options.referenceImagePaths?.length ? options.referenceImagePaths
-            : options.useTargetReference === false ? [] : schemaReferences.length ? schemaReferences : [relativeTarget];
-        const referenceImagePaths = references.map(ref => /^https?:\/\//i.test(ref) ? ref
+                return path.posix.join('src/theme', themeId, normalized);
+            })
+            : [];
+        const references = options.referenceImagePaths?.length
+            ? options.referenceImagePaths
+            : options.useTargetReference === false
+                ? []
+                : schemaReferences.length
+                    ? schemaReferences
+                    : [relativeTarget];
+        const referenceImagePaths = references.map((ref) => /^https?:\/\//i.test(ref)
+            ? ref
             : path.relative(realpathSync(root), canonicalProjectPath(root, ref)).replace(/\\/g, '/'));
         const hasSchemaBackground = typeof ext?.remove_background === 'boolean';
         if (!hasSchemaBackground && targetHasTransparency === undefined) {
-            targetHasTransparency = !!targetMeta.hasAlpha && (await sharp(target).stats()).channels.at(-1).min < 250;
+            targetHasTransparency =
+                !!targetMeta.hasAlpha && (await sharp(target).stats()).channels.at(-1).min < 250;
         }
         const removeBackground = resolveImageBackgroundRequirement({
             prompt: options.prompt ?? '',
@@ -171,12 +210,16 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
             targetAssetPath: relativeTarget,
             fieldPath: field?.path,
             referenceImagePaths,
-            width: delivery.width, height: delivery.height,
+            width: delivery.width,
+            height: delivery.height,
             aspectRatio: typeof ext?.ratio === 'string' ? ext.ratio : `${delivery.width}:${delivery.height}`,
             outputFormat: (removeBackground && delivery.format === 'jpeg' && !delivery.fromSchemaMimeType
-                ? 'png' : delivery.format),
+                ? 'png'
+                : delivery.format),
             outputFormatFromSchema: delivery.fromSchemaMimeType,
-            fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
+            fitMode: delivery.fitMode,
+            removeBackground: delivery.removeBackground,
+            paddingColor: delivery.paddingColor,
             removeBackgroundFromSchema: hasSchemaBackground,
             imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
         };
@@ -188,33 +231,40 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
             contexts.push(await contextForField(field));
         }
         catch (error) {
-            const selected = field?.path.length === targetFieldPath?.length
-                && field?.path.every((key, index) => key === targetFieldPath?.[index]);
+            const selected = field?.path.length === targetFieldPath?.length &&
+                field?.path.every((key, index) => key === targetFieldPath?.[index]);
             if (!targetFieldPath || selected)
                 throw error;
             // Invalid sibling requirements still protect the original shared file.
             unresolvedSharedField = true;
         }
     }
-    const context = targetFieldPath ? contexts.find(candidate => candidate.fieldPath?.length === targetFieldPath.length
-        && candidate.fieldPath.every((key, index) => key === targetFieldPath[index])) : contexts[0];
+    const context = targetFieldPath
+        ? contexts.find((candidate) => candidate.fieldPath?.length === targetFieldPath.length &&
+            candidate.fieldPath.every((key, index) => key === targetFieldPath[index]))
+        : contexts[0];
     const deliveryKey = ({ fieldPath: _fieldPath, outputFormatFromSchema: _formatSource, removeBackgroundFromSchema: _backgroundSource, aspectRatio, ...delivery }) => {
         const ratio = aspectRatio.match(/^\s*(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)\s*$/);
-        return JSON.stringify({ ...delivery, aspectRatio: ratio && Number(ratio[2]) > 0 ? Number(ratio[1]) / Number(ratio[2]) : aspectRatio });
+        return JSON.stringify({
+            ...delivery,
+            aspectRatio: ratio && Number(ratio[2]) > 0 ? Number(ratio[1]) / Number(ratio[2]) : aspectRatio,
+        });
     };
-    const conflicting = unresolvedSharedField || contexts.some(candidate => deliveryKey(candidate) !== deliveryKey(context));
+    const conflicting = unresolvedSharedField ||
+        contexts.some((candidate) => deliveryKey(candidate) !== deliveryKey(context));
     if (conflicting && !targetFieldPath) {
-        throw new Error(`Multiple image fields use ${relativeTarget} with different references or delivery constraints. Set targetFieldPath (or --target-field-path) to one of: ${fields.map(field => JSON.stringify(field.path)).join(', ')}.`);
+        throw new Error(`Multiple image fields use ${relativeTarget} with different references or delivery constraints. Set targetFieldPath (or --target-field-path) to one of: ${fields.map((field) => JSON.stringify(field.path)).join(', ')}.`);
     }
     if (targetFieldPath) {
         // A separate output retains exactly the selected field's requirements.
-        if (conflicting || contexts.some(candidate => (candidate.outputFormatFromSchema && !context.outputFormatFromSchema)
-            || (candidate.removeBackgroundFromSchema && !context.removeBackgroundFromSchema)))
+        if (conflicting ||
+            contexts.some((candidate) => (candidate.outputFormatFromSchema && !context.outputFormatFromSchema) ||
+                (candidate.removeBackgroundFromSchema && !context.removeBackgroundFromSchema)))
             context.requiresSeparateOutput = true;
     }
     else {
-        context.outputFormatFromSchema = contexts.some(candidate => candidate.outputFormatFromSchema);
-        context.removeBackgroundFromSchema = contexts.some(candidate => candidate.removeBackgroundFromSchema);
+        context.outputFormatFromSchema = contexts.some((candidate) => candidate.outputFormatFromSchema);
+        context.removeBackgroundFromSchema = contexts.some((candidate) => candidate.removeBackgroundFromSchema);
     }
     assertImageAssetOutputPaths(context, options.outputPaths ?? [], root, options.allowedOutputRoots);
     if (context.referenceImagePaths.length > 8)

package/dist/workspace-runtime/codex/app-server.js

@@ -33,7 +33,7 @@ function withModelShell(config, modelConfigId) {
 const ENGINEERING_BATCH_INSTRUCTIONS = [
     'For a single replica, work directly in the current repository and preserve the user-provided references. Do not create a batch for a single replica.',
     'If the repository is empty, initialize it using the default starter template before implementing the replica; preserve existing workspace metadata and files. If the template is unavailable, report the failure instead of substituting another template.',
-    'A repository is empty only when it has no user project files, including ignored files; workspace metadata, skills, references and attachments do not count as a project. For an empty repository, run playcraft references prepare-starter-template --json and merge the returned staged template into the current repository. Preserve existing files and workspace configuration, merge .gitignore without replacing it, preserve executable permissions, and report conflicts or preparation failures instead of overwriting files or creating a batch. Once finished, remove only the exact staging directory returned by the command.',
+    'A repository is empty only when it has no user project files, including ignored files; workspace metadata, skills, references and attachments do not count as a project. For an empty repository, run playcraft references prepare-starter-template --template <cocos|threejs> --json and merge the returned staged template into the current repository. Always declare --template explicitly: use threejs when the user asks for a Three.js project, and cocos when the user asks for Cocos or does not specify an engine. Preserve existing files and workspace configuration, merge .gitignore without replacing it, preserve executable permissions, and report conflicts or preparation failures instead of overwriting files or creating a batch. Once finished, remove only the exact staging directory returned by the command.',
     'When the user requests multiple independent engineering variants, create a real platform batch using playcraft tools create-batch --prompt <the complete request, including constraints established in this conversation> --workspace-id <the trusted batch request workspaceId> --source-directory <the trusted batch request sourceDirectoryName> --client-request-id <the trusted batch request clientRequestId> --json.',
     'Distinguish independent variants from multiple assets, levels or themes within one engineering project. Use the current session directory supplied by the runtime as the batch source; do not infer it from a preview or another conversation.',
     'The platform freezes the current source and generates each planned variant in its own Remix directory. Submission authorizes automatic generation without another prompt approval. Keep the source unchanged for this batch; do not replace independent variants with theme switching in the source.',

package/dist/workspace-runtime/codex/remix-references-broker.js

@@ -183,7 +183,7 @@ export class WorkspaceRemixReferencesBroker {
                     sessionId: context.sessionId, wait: false,
                 }, async () => {
                     await this.current(context, valid, true);
-                    const raw = await this.upstream(scope, { action: 'starter-template' }, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES);
+                    const raw = await this.upstream(scope, { action: 'starter-template', templateId: input.templateId }, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES);
                     await this.current(context, valid, true);
                     return prepareStarterTemplate(context.cwd, raw, () => this.operation(context, valid, true));
                 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.82",
+  "version": "0.1.84-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -57,8 +57,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.82",
-    "@playcraft/common": "0.1.82",
+    "@playcraft/build": "0.1.84-beta",
+    "@playcraft/common": "0.1.84-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",