@playcraft/cli 0.1.42 → 0.1.44-beta

package/project-templates/threejs/.claude/skills/playcraft-image-generation/reference/prompt-cookbook.md

@@ -1,23 +1,21 @@
 # Image Generation Prompt Cookbook
 
-> 适用于 PlayCraft CLI (Command-Line Interface, 命令行工具) `playcraft tools generate-image` 及沙箱生图工具。
+> 适用于 PlayCraft CLI `playcraft tools generate-image`。
 > 所有模型均适用；gpt-image-2 类模型对英文 prompt 理解最准确，优先写英文。
 
-透明交付通过 `background: transparent` / `--background transparent` 或目标字段配置表达。用户未明确要求背景且字段没有明确不透明约束时，默认透明，包括卡牌、棋子和面板。下方常规前景模板描述主体、文字、风格、构图与材质；源图背景遵循主文第 2 节：Image 2.5 由后端组装，不追加背景后缀；明确选用其他模型时，首次请求需追加单一 `on a uniform solid pure white background for subsequent background removal`。不要同时要求透明、白底与色幕。用户或字段明确要求完整场景时可以描述背景内容；矩形本体的白色牌面属于前景，应在透明画布上保留。独立色幕流程见主文第 3 节，中间图必须关闭自动去背。
-
 ---
 
 ## 一、Prompt 万能公式
 
 ```
-[主体描述] + [风格/介质] + [构图/视角] + [场景内容（如需要）] + [质量修饰词]
+[主体描述] + [风格/介质] + [构图/视角] + [背景] + [质量修饰词]
 ```
 
 **示例**：
 
 ```
 A golden sword icon, flat 2D vector style, centered composition,
-isolated subject, clean crisp edges, game UI asset, high quality
+white background, clean crisp edges, game UI asset, high quality
 ```
 
 ---
@@ -28,13 +26,12 @@ isolated subject, clean crisp edges, game UI asset, high quality
 
 ```
 A [物品名] icon, flat 2D vector illustration, bold outlines,
-vibrant colors, centered composition, isolated subject,
+vibrant colors, centered composition, white background,
 no shadow, no gradient, game UI style, sharp crisp edges
 ```
 
 - 关键词：`flat 2D` / `bold outlines` / `centered` / `no shadow` / `game UI style`
 - 避免：`3D` / `realistic` / `photographic` / `drop shadow`
-- 需要透明交付时传 `background: transparent` / `--background transparent`。
 
 ### 🃏 卡牌 / 棋子 / 方块（Rectangular Tiles）
 
@@ -53,11 +50,12 @@ sharp clean edges, centered on white background
 ```
 A [角色描述] character, full body visible, game sprite style,
 [艺术风格: pixel art / cartoon / chibi / realistic],
-isolated subject,
+isolated on solid bright green #00FF00 background,
 centered, facing forward / side view, clean silhouette
 ```
 
-- 需要透明交付 → `background: transparent` / `--background transparent`，按主文第 2 节准备源图背景，由后端去背并完成验收。
+- 需要透明背景 → **绿幕策略**，prompt 加 `"on solid bright green #00FF00 background, isolated"`
+- 后处理：`remove-background --tolerance 25`
 
 ### 🌄 场景背景（Backgrounds）
 
@@ -122,7 +120,7 @@ Grid layout, equal cell size, no borders between cells. Bold black ink for spade
 **图标集示例**（一批 9 个图标）：
 
 ```
-Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, isolated subjects.
+Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, white background.
 [Row1,Col1]: sword icon; [Row1,Col2]: shield icon; [Row1,Col3]: bow and arrow icon;
 [Row2,Col1]: magic staff icon; [Row2,Col2]: potion bottle icon; [Row2,Col3]: scroll icon;
 [Row3,Col1]: coin gold icon; [Row3,Col2]: gem diamond icon; [Row3,Col3]: key icon.
@@ -131,18 +129,17 @@ Each icon centered in its cell, bold outlines, vibrant colors, no shadow.
 
 **背景选择（重要！）**：
 
-| 素材类型                            | 交付要求                                              | 切分后处理                        |
-| ----------------------------------- | ----------------------------------------------------- | --------------------------------- |
-| 独立元素（角色/车/道具/图标）需透明 | `--background transparent`，按主文第 2 节准备源图背景 | 保留透明通道，验证每格前景与边缘  |
-| 卡牌/棋子/UI 面板（矩形本体）       | 默认 `--background transparent`，保留牌面与边框       | 验证本体外透明，按目标尺寸 resize |
-| 用户/字段明确要求保留背景的最终素材 | `--background opaque`，整张图片不透明                 | 保留背景，按目标尺寸 resize       |
+| 素材类型                            | prompt 背景写法                                     | 切分后处理                         |
+| ----------------------------------- | --------------------------------------------------- | ---------------------------------- |
+| 独立元素（角色/车/道具/图标）需透明 | `isolated on solid bright green #00FF00 background` | `remove-background --tolerance 25` |
+| 卡牌/棋子/UI 面板（矩形本体）       | `white background, no shadow`                       | 直接 resize，不去背景              |
 
 **注意事项**：
 
 - 每批最多 **4×4 = 16 个元素**，超过会出现混乱
 - 每个格的描述要精确，包含特征性视觉元素
 - 切分后用 `sprite-split --rows N --columns M` 按网格切分
-- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)：`backgroundMode='automatic'` 为常规流程，`removeBg` 表示最终是否透明。独立色幕需显式设 `backgroundMode='chroma'`、所选模型和色幕颜色；脚本关闭整板自动去背，切分后逐格去背。
+- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
 
 ---
 
@@ -186,7 +183,7 @@ gpt-image-2 是目前质量最高的文生图模型，prompt 套路略有不同
 - **英文 prompt 效果最佳**，中文理解也不错但英文更稳定
 - 对**复杂场景**、**细节描述**处理能力远超其他模型
 - 支持**图生图 edit 模式**（传 `--reference-image`），局部编辑能力强
-- 不支持原生透明 PNG (Portable Network Graphics, 便携式网络图形) 输出（ALPHA = no）；透明交付仍由工具后处理。明确选择独立色幕制作时再按主文第 3 节处理。
+- 不支持透明 PNG 输出（ALPHA = no），需绿幕策略
 
 ### prompt 格式建议
 
@@ -234,7 +231,6 @@ elements centered in each cell, no borders between cells.
 ```bash
 playcraft tools generate-image \
   --prompt "A sword icon, flat 2D..." \
-  --background transparent \
   --output assets/gen/sword \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -252,7 +248,6 @@ playcraft tools generate-image \
 # 一次 API 调用生成 4 个候选，选最好的（比 4 次独立调用更高效）
 playcraft tools generate-image \
   --prompt "..." \
-  --background "$BACKGROUND_MODE" \
   --output "test/concept" \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -275,8 +270,6 @@ playcraft tools generate-image \
 >
 > 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，Game Designer `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
 
-下方独立界面前景通过 `background: transparent` / `--background transparent` 要求最终透明；模板描述主体，调用前按主文第 2 节补充适用于所选模型的源图背景。
-
 ### 🟠 CTA 按钮（Call-to-Action Button）
 
 ```
@@ -287,13 +280,13 @@ Important details: [bright orange / gold / green] gradient fill,
   subtle drop shadow below button, glossy highlight on top edge,
   3px white inner border, corners rounded radius 24px
 Use case: Game ad install button, isolated asset, HTML5 playable ad
-Constraints: No extra elements, centered, clean crisp edges,
+Constraints: Transparent background, no extra elements, centered, clean crisp edges,
   no watermark
 ```
 
 - CTA 颜色必须是游戏画面中**最少使用**的颜色（对比稀缺性原则）
 - 触控目标区域 ≥ 48×48px，生成建议尺寸 360×120px（9:3 比例）
-- 后处理由工具完成，验证最终透明背景、文字与边缘。
+- 后处理：不需要去背景（直接生成透明背景或用绿幕）
 
 ---
 
@@ -306,7 +299,7 @@ Important details: [color] filled portion [80% of total width], unfilled portion
   rounded end caps, thin outer frame in [darker shade],
   optional inner glow on filled section
 Use case: Game HUD progress indicator, isolated UI element
-Constraints: Horizontal orientation, no text labels,
+Constraints: Transparent background, horizontal orientation, no text labels,
   clean edges, no watermark
 ```
 
@@ -324,7 +317,8 @@ Important details: warm skin tone, white sleeve cuff visible at wrist,
   soft drop shadow beneath finger tip, friendly approachable style,
   [optional: subtle animated glow ring around fingertip]
 Use case: Tutorial overlay tap gesture for playable ad, points toward target element
-Constraints: No extra limbs or elements, finger pointing at bottom-center
+Constraints: Transparent background, PNG with alpha channel,
+  no extra limbs or elements, finger pointing at bottom-center
 ```
 
 **箭头变体**（更简洁）：
@@ -334,7 +328,7 @@ Subject: Bold cartoon arrow pointing [down / right], game tutorial UI
 Style: flat 2D, thick outline 4px, rounded arrowhead
 Important details: [bright yellow / white] fill, [dark outline],
   slight perspective tilt for depth, attention-grabbing
-Constraints: Single clean arrow shape, no text
+Constraints: Transparent background, single clean arrow shape, no text
 ```
 
 ---
@@ -348,7 +342,7 @@ Important details: white or [light color] fill, [2–3px] dark outline,
   tail pointing [down-left / down-center], interior empty for text overlay,
   subtle inner shadow or gradient
 Use case: Game tutorial hint tooltip, isolated UI asset
-Constraints: No text inside, clean edges,
+Constraints: Transparent background, no text inside, clean edges,
   no watermark, no extra decorations
 ```
 
@@ -368,7 +362,7 @@ Important details: [treasure chest]: lid slightly ajar, golden glow escaping fro
   [gold coins]: scattered pile, gleaming highlights, not neatly stacked (implies uncollected);
   [gem crystal]: large, brilliant facets, floating above ground, clearly valuable
 Use case: EndCard reward visual, creates FOMO and drives install
-Constraints: Centered, isolated subject,
+Constraints: Transparent background, centered, isolated subject,
   no CTA text (added separately), warm celebratory lighting
 ```
 
@@ -379,19 +373,25 @@ Constraints: Centered, isolated subject,
 
 ### 📊 UI 元素背景处理规则速查
 
-CTA 按钮、进度条、引导手势、对话气泡与 EndCard 奖励图标都通过 `background: transparent` / `--background transparent` 要求最终透明；主体内容使用上述模板，源图背景按主文第 2 节准备。交付后验证文字、完整前景及深浅背景上的边缘。独立色幕制作沿用主文第 3 节的单一背景与独立去背流程。
+| UI 元素类型      | prompt 背景写法                                 | 后处理                         |
+| ---------------- | ----------------------------------------------- | ------------------------------ |
+| CTA 按钮         | `transparent background` 或绿幕                 | floodfill 去背                 |
+| 进度条           | `transparent background` 或绿幕                 | floodfill 去背                 |
+| 引导手势         | `transparent background, PNG with alpha`        | floodfill 去背（tolerance 25） |
+| 对话气泡         | `transparent background` 或绿幕                 | floodfill 去背                 |
+| EndCard 奖励图标 | 绿幕（`solid bright green #00FF00 background`） | floodfill 去背（tolerance 25） |
 
 ---
 
 ## 六、常见问题 & 修正方案
 
-| 问题               | 原因                 | 修正                                                                     |
-| ------------------ | -------------------- | ------------------------------------------------------------------------ |
-| 图标边缘有阴影     | 模型默认加立体效果   | 加 `no shadow, no drop shadow, flat 2D`                                  |
-| 构图不居中         | 没有明确指定         | 加 `centered composition, subject centered`                              |
-| 背景不干净         | 交付要求或处理不匹配 | 核对背景开关、字段配置及模型对应的源图规则；检查最终验收，不混加背景要求 |
-| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`                                  |
-| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张                                   |
-| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`                                       |
-| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes`                         |
-| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                                               |
+| 问题               | 原因                 | 修正                                             |
+| ------------------ | -------------------- | ------------------------------------------------ |
+| 图标边缘有阴影     | 模型默认加立体效果   | 加 `no shadow, no drop shadow, flat 2D`          |
+| 构图不居中         | 没有明确指定         | 加 `centered composition, subject centered`      |
+| 背景不干净         | 背景描述不够明确     | 加 `solid white background, isolated` 或绿幕策略 |
+| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`          |
+| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张           |
+| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`               |
+| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes` |
+| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                       |

package/dist/commands/tools-image-context.js

@@ -1,29 +0,0 @@
-import { readImageAssetContext } from '../utils/image-asset-context.js';
-import { collectReferenceImagePaths, handleError, parseImageTargetFieldPath } from './tools-utils.js';
-export function registerImageContextCommand(tools) {
-    tools.command('image-context')
-        .description('Read image asset reference and delivery constraints locally; does not generate an image')
-        .requiredOption('--asset-path <path>', 'Existing image asset path relative to the project')
-        .option('--target-field-path <path>', 'Target image field as an array of keys, e.g. ["endUI","playButton"]', parseImageTargetFieldPath)
-        .option('--output-path <path>', 'Intended output path; checks shared asset protection before generation', collectReferenceImagePaths, [])
-        .option('--allowed-output-root <path>', 'Additional output directory authorized by the caller; does not allow external references', collectReferenceImagePaths, [])
-        .option('--reference-image <path>', 'Explicit local reference; may be repeated', collectReferenceImagePaths, [])
-        .option('--no-target-reference', 'Do not use the target schema or current asset as a reference')
-        .option('--prompt <text>', 'Generation request used to resolve background intent')
-        .option('--remove-background', 'Explicitly request verified transparency')
-        .option('--no-remove-background', 'Explicitly keep an opaque background')
-        .action(async (opts) => {
-        try {
-            console.log(JSON.stringify(await readImageAssetContext(opts.assetPath, process.cwd(), {
-                referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
-                ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
-                outputPaths: opts.outputPath,
-                allowedOutputRoots: opts.allowedOutputRoot,
-                prompt: opts.prompt, removeBackground: opts.removeBackground,
-            })));
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-}

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

@@ -1,228 +0,0 @@
-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';
-function isWithinDirectory(root, file) {
-    const relative = path.relative(root, file);
-    return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-}
-/** Resolve existing ancestors so a new workspace need not have been created yet. */
-function realPathWithParents(file) {
-    let ancestor = file;
-    while (!existsSync(ancestor)) {
-        const parent = path.dirname(ancestor);
-        if (parent === ancestor)
-            throw new Error(`Image path has no existing ancestor: ${file}`);
-        ancestor = parent;
-    }
-    return path.resolve(realpathSync(ancestor), path.relative(ancestor, file));
-}
-/** Resolve aliases and existing parent symlinks, including for a new output file. */
-function canonicalProjectPath(root, input) {
-    const mapped = input.startsWith('/project/') ? input.slice('/project/'.length) : input;
-    const file = path.resolve(root, mapped);
-    if (!isWithinDirectory(root, file)) {
-        throw new Error(`Image asset path is outside the project: ${input}`);
-    }
-    const real = realPathWithParents(file);
-    if (!isWithinDirectory(realPathWithParents(root), real)) {
-        throw new Error(`Image asset symlink is outside the project: ${input}`);
-    }
-    return real;
-}
-/** Check every extension a writer may choose before sending a generation request. */
-export function assertImageAssetOutputPaths(context, outputPaths, projectDir = process.cwd(), allowedOutputRoots = []) {
-    if (!context.requiresSeparateOutput)
-        return;
-    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))];
-    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}`))];
-        for (const candidate of candidates) {
-            const candidatePath = path.resolve(root, candidate);
-            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)) {
-                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.`);
-            }
-        }
-    }
-}
-/** Resolve only real files in this project, including legacy /project aliases. */
-function projectFile(root, input) {
-    const mapped = input.startsWith('/project/') ? input.slice('/project/'.length) : input;
-    const file = path.resolve(root, mapped);
-    if (!isWithinDirectory(root, file))
-        throw new Error(`Image asset path is outside the project: ${input}`);
-    const real = realpathSync(file);
-    if (!isWithinDirectory(realpathSync(root), real))
-        throw new Error(`Image asset symlink is outside the project: ${input}`);
-    return file;
-}
-/** 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))) {
-        throw new Error('targetFieldPath must be a non-empty array of non-empty field names.');
-    }
-    const root = path.resolve(projectDir);
-    const target = projectFile(root, assetPath);
-    const realTarget = realpathSync(target);
-    const targetStat = statSync(target);
-    const relativeTarget = path.relative(root, target).replace(/\\/g, '/');
-    const themeMatch = relativeTarget.match(/^src\/theme\/([^/]+)\/assets\//);
-    let fields = [];
-    const schemaFile = path.join(root, THEME_SCHEMA_PATH);
-    if (themeMatch && existsSync(schemaFile)) {
-        const schema = JSON5.parse(readFileSync(projectFile(root, THEME_SCHEMA_PATH), 'utf8'));
-        const dataPath = themeDataPath(themeMatch[1]);
-        const data = existsSync(path.join(root, dataPath))
-            ? JSON5.parse(readFileSync(projectFile(root, dataPath), 'utf8')) : {};
-        const themeRoot = path.dirname(path.join(root, dataPath));
-        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)]);
-            }
-            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);
-            if (configuredPath === target)
-                return true;
-            try {
-                const candidateFile = projectFile(root, configuredPath);
-                if (!path.relative(realTarget, realpathSync(candidateFile)))
-                    return true;
-                const candidateStat = statSync(candidateFile);
-                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)
-            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(', ')}.`);
-        }
-    }
-    else if (targetFieldPath) {
-        throw new Error('targetFieldPath requires an asset with a matching theme schema.');
-    }
-    const targetMeta = await sharp(target).metadata();
-    let targetHasTransparency;
-    const contextForField = async (field) => {
-        const xp = field?.schema.xplatform;
-        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 => {
-                const raw = ref.trim().replace(/\\/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))
-                    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
-            : 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;
-        }
-        const removeBackground = resolveImageBackgroundRequirement({
-            prompt: options.prompt ?? '',
-            schemaRemoveBackground: hasSchemaBackground ? ext.remove_background : undefined,
-            removeBackground: options.removeBackground,
-            fallbackRemoveBackground: targetHasTransparency ?? false,
-        });
-        const delivery = resolveAiImageTargetConstraints({
-            schemaResolution: ext?.resolution,
-            schemaMimeType: xp?.mime_type,
-            schemaFitMode: xp?.fit_mode ?? ext?.fit_mode,
-            schemaRemoveBackground: removeBackground,
-            schemaPaddingColor: ext?.padding_color,
-            assetPath: relativeTarget,
-            referenceWidth: targetMeta.width,
-            referenceHeight: targetMeta.height,
-            referenceFormat: targetMeta.format,
-        });
-        if (!['png', 'webp', 'jpeg'].includes(delivery.format))
-            throw new Error('Unsupported image delivery format; use a dedicated animation or vector workflow.');
-        return {
-            targetAssetPath: relativeTarget,
-            fieldPath: field?.path,
-            referenceImagePaths,
-            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),
-            outputFormatFromSchema: delivery.fromSchemaMimeType,
-            fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
-            removeBackgroundFromSchema: hasSchemaBackground,
-            imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
-        };
-    };
-    const contexts = [];
-    let unresolvedSharedField = false;
-    for (const field of fields.length ? fields : [undefined]) {
-        try {
-            contexts.push(await contextForField(field));
-        }
-        catch (error) {
-            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 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 });
-    };
-    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(', ')}.`);
-    }
-    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)))
-            context.requiresSeparateOutput = true;
-    }
-    else {
-        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)
-        throw new Error('At most 8 reference images are allowed.');
-    for (const ref of context.referenceImagePaths) {
-        if (/^https?:\/\//i.test(ref))
-            throw new Error('Download the schema reference into the project before generating.');
-        await sharp(projectFile(root, ref)).metadata();
-    }
-    return context;
-}