hoi4-agent-tools 2.8.4 → 2.8.6

package/dist/hoi4_agent_tools/gui/source-graph.js

@@ -117,7 +117,27 @@ export function guiElementAttributeFidelity(key) {
     return 'unsupported';
 }
 function normalizeAssetPath(value) {
-    return value.replaceAll('\\', '/').replace(/^\.\//u, '').replace(/^\//u, '').toLowerCase();
+    return value
+        .replaceAll('\\', '/')
+        .replace(/^\/+|^\.\//u, '')
+        .replace(/\/+/gu, '/')
+        .toLowerCase();
+}
+function textureNodeFor(textureNodes, texturePath) {
+    const normalized = normalizeAssetPath(texturePath);
+    const extension = path.posix.extname(normalized);
+    const rasterExtensions = ['.png', '.bmp', '.tga', '.dds'];
+    const candidates = rasterExtensions.includes(extension)
+        ? [
+            normalized,
+            ...rasterExtensions
+                .filter((candidate) => candidate !== extension)
+                .map((candidate) => `${normalized.slice(0, -extension.length)}${candidate}`),
+        ]
+        : [normalized];
+    return candidates
+        .map((candidate) => textureNodes.get(candidate))
+        .find((value) => value !== undefined);
 }
 function scalarValue(value, constants) {
     const expanded = constants.get(value) ?? value;
@@ -197,6 +217,26 @@ function paradoxColour(value) {
     const argb = match[1];
     return `#${argb.slice(2)}${argb.slice(0, 2)}`.toLowerCase();
 }
+function textColoursFrom(block) {
+    const textColours = childBlocks(block, 'textcolors')[0];
+    if (textColours === undefined)
+        return {};
+    const result = {};
+    for (const entry of assignments(textColours)) {
+        if (entry.value.type !== 'block')
+            continue;
+        const channels = entry.value.entries
+            .filter((channel) => channel.type === 'scalar')
+            .map((channel) => Number(channel.value));
+        if (channels.length < 3 || channels.slice(0, 3).some((channel) => !Number.isFinite(channel)))
+            continue;
+        const [red, green, blue] = channels.map((channel) => Math.max(0, Math.min(255, Math.round(channel))));
+        result[entry.key.value] = `#${red.toString(16).padStart(2, '0')}${green
+            .toString(16)
+            .padStart(2, '0')}${blue.toString(16).padStart(2, '0')}`;
+    }
+    return result;
+}
 function sizeFrom(block) {
     const size = childBlocks(block, 'size')[0];
     if (size === undefined)
@@ -343,7 +383,7 @@ function indexGuiElements(document, file, fileNodeId, nodes, edges, elements) {
         }
     }
 }
-function indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites, fonts) {
+function indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites, fonts, globalTextColours) {
     const walk = (block) => {
         for (const assignment of assignments(block)) {
             if (assignment.value.type !== 'block')
@@ -436,18 +476,27 @@ function indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites,
                         .map((entry) => entry.value));
                     const colour = paradoxColour(firstScalarInsensitive(child, 'color', 'colour'));
                     const borderColour = paradoxColour(firstScalarInsensitive(child, 'border_color', 'borderColor', 'border_colour'));
-                    const id = deterministicId('gui_font', { path: file.displayPath, name });
+                    const textColours = textColoursFrom(child);
+                    const override = assignment.key.value === 'bitmapfont_override';
+                    const id = deterministicId('gui_font', {
+                        path: file.displayPath,
+                        name,
+                        override,
+                        languages,
+                        assetPaths,
+                    });
                     const font = {
                         id,
                         name,
                         sourcePath: file.displayPath,
                         location: nodeLocation(document, assignment, name),
                         kind: 'bitmapfont',
-                        override: assignment.key.value === 'bitmapfont_override',
+                        override,
                         languages,
                         assetPaths,
                         ...(colour === undefined ? {} : { colour }),
                         ...(borderColour === undefined ? {} : { borderColour }),
+                        ...(Object.keys(textColours).length === 0 ? {} : { textColours }),
                         rawSource: raw(document, assignment),
                     };
                     addDomainEntry(fonts, font, 'font');
@@ -464,11 +513,15 @@ function indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites,
                             assetPaths,
                             ...(colour === undefined ? {} : { colour }),
                             ...(borderColour === undefined ? {} : { borderColour }),
+                            ...(Object.keys(textColours).length === 0 ? {} : { textColours }),
                         },
                     });
                     addEdge(edges, 'contains', fileNodeId, id, true, {}, font.location);
                 }
             }
+            if (assignment.key.value === 'bitmapfonts') {
+                Object.assign(globalTextColours, textColoursFrom(child));
+            }
             walk(child);
         }
     };
@@ -750,8 +803,21 @@ function indexScriptedLocalisation(document, file, fileNodeId, nodes, edges, def
         const name = firstScalar(assignment.value, 'name')?.value;
         if (name === undefined)
             continue;
-        const localisationKeys = childBlocks(assignment.value, 'text')
-            .flatMap((textBlock) => firstScalar(textBlock, 'localisation_key')?.value ?? [])
+        const choices = childBlocks(assignment.value, 'text').flatMap((textBlock) => {
+            const localisationKey = firstScalarInsensitive(textBlock, 'localisation_key', 'localization_key');
+            if (localisationKey === undefined)
+                return [];
+            const trigger = childBlocks(textBlock, 'trigger')[0];
+            return [
+                {
+                    localisationKey,
+                    ...(trigger === undefined ? {} : { triggerExpression: raw(document, trigger) }),
+                    rawSource: raw(document, textBlock),
+                },
+            ];
+        });
+        const localisationKeys = choices
+            .map(({ localisationKey }) => localisationKey)
             .sort((left, right) => compareCodeUnits(left, right));
         const id = deterministicId('scripted_localisation', { path: file.displayPath, name });
         const location = nodeLocation(document, assignment, name);
@@ -761,6 +827,7 @@ function indexScriptedLocalisation(document, file, fileNodeId, nodes, edges, def
             sourcePath: file.displayPath,
             location,
             localisationKeys,
+            choices,
             rawSource: raw(document, assignment),
         }, 'scripted localisation');
         addNode(nodes, {
@@ -769,7 +836,13 @@ function indexScriptedLocalisation(document, file, fileNodeId, nodes, edges, def
             name,
             path: file.displayPath,
             location,
-            metadata: { localisationKeys },
+            metadata: {
+                localisationKeys,
+                choices: choices.map(({ localisationKey, triggerExpression }) => ({
+                    localisationKey,
+                    ...(triggerExpression === undefined ? {} : { triggerExpression }),
+                })),
+            },
         });
         addEdge(edges, 'contains', fileNodeId, id, true, {}, location);
     }
@@ -841,7 +914,7 @@ function linkGraph(nodes, edges, elements, sprites, fonts, scriptedGuis, scripte
         for (const [index, texturePath] of [sprite.texturePath, sprite.texturePath2].entries()) {
             if (texturePath === undefined)
                 continue;
-            const textureId = textureNodes.get(normalizeAssetPath(texturePath));
+            const textureId = textureNodeFor(textureNodes, texturePath);
             addEdge(edges, 'uses_texture', sprite.id, textureId ?? `texture:${normalizeAssetPath(texturePath)}`, textureId !== undefined, { texturePath, slot: index + 1 }, sprite.location);
         }
         const candidates = [
@@ -1046,6 +1119,7 @@ export function buildGuiSourceGraph(files, sharedIndex) {
     const elements = [];
     const sprites = [];
     const fonts = [];
+    const textColours = {};
     const scriptedGuis = [];
     const animationSources = [];
     const scriptedLocalisation = [];
@@ -1167,7 +1241,7 @@ export function buildGuiSourceGraph(files, sharedIndex) {
         if (kind === 'gui_file')
             indexGuiElements(document, file, fileNodeId, nodes, edges, elements);
         if (kind === 'gfx_file') {
-            indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites, fonts);
+            indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites, fonts, textColours);
         }
         if (kind === 'scripted_gui_file') {
             indexScriptedGuis(document, file, fileNodeId, nodes, edges, scriptedGuis);
@@ -1247,6 +1321,7 @@ export function buildGuiSourceGraph(files, sharedIndex) {
         elements,
         sprites,
         fonts,
+        textColours: Object.fromEntries(Object.entries(textColours).sort(([left], [right]) => compareCodeUnits(left, right))),
         scriptedGuis,
         animationSources,
         scriptedLocalisation,

package/dist/hoi4_agent_tools/gui/studio.js

@@ -19,7 +19,8 @@ import { projectGuiGraphForArtifact } from './inspection-artifact.js';
 import { buildGuiScene } from './layout.js';
 import { GUI_VALIDATION_MAX_DIAGNOSTICS } from './limits.js';
 import { compareGuiImages, galleryDimensions, renderGallerySvg, renderGuiScene, } from './renderer.js';
-import { parsePreviewScenario } from './scenario.js';
+import { generateGuiPreviewScenarios } from './scenario-generator.js';
+import { parseGeneratedScenarioOptions, parsePreviewScenario } from './scenario.js';
 import { buildGuiSourceGraph } from './source-graph.js';
 import { assertGuiSourcePatchesSafe } from './source-patch.js';
 import { validateGuiScene, validateResolutionDrift, validateStateMatrix } from './validators.js';
@@ -327,7 +328,7 @@ function localisationIconSpriteCandidates(token) {
     const normalized = token.startsWith('GFX_') ? token : `GFX_${token}`;
     return [...new Set([normalized, `${normalized}_texticon`, `${normalized}_text_icon`])];
 }
-function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = []) {
+export function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = [], languages = ['l_english']) {
     const spriteNames = new Set(additionalSpriteNames);
     const fontNames = new Set();
     const textValues = new Set();
@@ -346,6 +347,37 @@ function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNam
                 spriteNames.add(candidate);
         }
     }
+    const relatedScriptedGuiNames = new Set(graph.scriptedGuis
+        .filter((definition) => definition.windowName === windowName || definition.parentWindowName === windowName)
+        .map(({ name }) => name));
+    let addedRelatedScriptedGui = true;
+    while (addedRelatedScriptedGui) {
+        addedRelatedScriptedGui = false;
+        for (const definition of graph.scriptedGuis) {
+            if (definition.parentScriptedGui === undefined ||
+                !relatedScriptedGuiNames.has(definition.parentScriptedGui) ||
+                relatedScriptedGuiNames.has(definition.name))
+                continue;
+            relatedScriptedGuiNames.add(definition.name);
+            addedRelatedScriptedGui = true;
+        }
+    }
+    const dynamicImageTokens = new Set(graph.scriptedGuis
+        .filter(({ name }) => relatedScriptedGuiNames.has(name))
+        .flatMap(({ propertyDefinitions }) => propertyDefinitions)
+        .flatMap(({ attributes }) => {
+        const image = Object.entries(attributes).find(([key]) => key.toLocaleLowerCase('en-US') === 'image')?.[1];
+        if (typeof image !== 'string')
+            return [];
+        const match = /^\[([^\]]+)\]$/u.exec(image);
+        return match?.[1] === undefined ? [] : [match[1]];
+    }));
+    for (const definition of graph.scriptedLocalisation) {
+        if (!dynamicImageTokens.has(definition.name))
+            continue;
+        for (const candidate of definition.localisationKeys)
+            spriteNames.add(candidate);
+    }
     const spritesByName = new Map(graph.sprites.map((sprite) => [sprite.name.toLocaleLowerCase('en-US'), sprite]));
     const selectedSprites = new Map();
     const pendingSprites = [...spriteNames];
@@ -365,7 +397,17 @@ function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNam
     }
     const selectedManifests = graph.animationSources.filter(({ sprite }) => selectedSprites.has(sprite.toLocaleLowerCase('en-US')));
     const selectedFontNames = new Set([...fontNames].map((name) => name.toLocaleLowerCase('en-US')));
-    const selectedFonts = graph.fonts.filter(({ name }) => selectedFontNames.has(name.toLocaleLowerCase('en-US')));
+    const normalizedLanguages = new Set(languages.flatMap((language) => {
+        const normalized = language.toLocaleLowerCase('en-US');
+        return [normalized, normalized.replace(/^l_/u, '')];
+    }));
+    const selectedFonts = graph.fonts.filter(({ name, languages: fontLanguages }) => selectedFontNames.has(name.toLocaleLowerCase('en-US')) &&
+        (fontLanguages.length === 0 ||
+            fontLanguages.some((language) => {
+                const normalized = language.toLocaleLowerCase('en-US');
+                return (normalizedLanguages.has(normalized) ||
+                    normalizedLanguages.has(normalized.replace(/^l_/u, '')));
+            })));
     const references = [
         ...[...selectedSprites.values()].flatMap(({ texturePath, texturePath2 }) => [texturePath, texturePath2].filter((value) => value !== undefined)),
         ...selectedFonts.flatMap(({ assetPaths }) => assetPaths),
@@ -664,7 +706,7 @@ export class ScriptedGuiStudio {
         const definitionFiles = mergeScannedFiles(layoutFiles, linkedDefinitions.files, localisation.files);
         const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`);
         assertTargetWindowAvailable(definitions.graph, windowName);
-        const referencedPatterns = referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames);
+        const referencedPatterns = referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages);
         const exactReferenced = referencedPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -702,10 +744,24 @@ export class ScriptedGuiStudio {
     }
     async lint(input) {
         input.signal?.throwIfAborted();
-        const scenario = parsePreviewScenario(input.scenario);
-        const relatedScenarios = (input.relatedScenarios ?? []).map(parsePreviewScenario);
+        const placeholderScenario = parsePreviewScenario(input.scenario);
+        const explicitRelatedScenarios = (input.relatedScenarios ?? []).map(parsePreviewScenario);
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios]));
+        const generatedOptions = input.generatedScenarios === undefined
+            ? undefined
+            : parseGeneratedScenarioOptions(input.generatedScenarios);
+        const generatedScenarios = generatedOptions === undefined
+            ? []
+            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions);
+        const scenario = generatedScenarios[0] ?? placeholderScenario;
+        const relatedScenarios = [
+            ...(generatedOptions?.preservePlaceholder === true && generatedScenarios.length > 0
+                ? [placeholderScenario]
+                : []),
+            ...generatedScenarios.slice(1),
+            ...explicitRelatedScenarios,
+        ];
         assertUniqueScenarioIds([scenario, ...relatedScenarios]);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [scenario.language, ...relatedScenarios.map(({ language }) => language)], scenarioSpriteNames([scenario, ...relatedScenarios]));
         const budget = new RenderBudget();
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
@@ -756,15 +812,37 @@ export class ScriptedGuiStudio {
         input.signal?.throwIfAborted();
         const budget = new RenderBudget();
         const workspace = this.resolver.get(input.workspaceId, input.principal);
-        const scenario = parsePreviewScenario(input.scenario);
-        const relatedScenarios = (input.relatedScenarios ?? []).map(parsePreviewScenario);
-        assertUniqueScenarioIds([scenario, ...relatedScenarios]);
-        const baselineScenario = parsePreviewScenario(input.comparisonScenario ?? { ...scenario, id: `${scenario.id}-comparison`, state: 'normal' });
+        const placeholderScenario = parsePreviewScenario(input.scenario);
+        const explicitRelatedScenarios = (input.relatedScenarios ?? []).map(parsePreviewScenario);
+        const requestedBaselineScenario = input.comparisonScenario === undefined
+            ? undefined
+            : parsePreviewScenario(input.comparisonScenario);
         const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [
-            scenario.language,
-            baselineScenario.language,
-            ...relatedScenarios.map(({ language }) => language),
-        ], scenarioSpriteNames([scenario, baselineScenario, ...relatedScenarios]));
+            placeholderScenario.language,
+            ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario.language]),
+            ...explicitRelatedScenarios.map(({ language }) => language),
+        ], scenarioSpriteNames([
+            placeholderScenario,
+            ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
+            ...explicitRelatedScenarios,
+        ]));
+        const generatedOptions = input.generatedScenarios === undefined
+            ? undefined
+            : parseGeneratedScenarioOptions(input.generatedScenarios);
+        const generatedScenarios = generatedOptions === undefined
+            ? []
+            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions);
+        const scenario = generatedScenarios[0] ?? placeholderScenario;
+        const relatedScenarios = [
+            ...(generatedOptions?.preservePlaceholder === true && generatedScenarios.length > 0
+                ? [placeholderScenario]
+                : []),
+            ...generatedScenarios.slice(1),
+            ...explicitRelatedScenarios,
+        ];
+        assertUniqueScenarioIds([scenario, ...relatedScenarios]);
+        const baselineScenario = requestedBaselineScenario ??
+            parsePreviewScenario({ ...scenario, id: `${scenario.id}-comparison`, state: 'normal' });
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
         const render = await renderGuiScene(scene, undefined, input.signal, budget);
@@ -1063,7 +1141,7 @@ export class ScriptedGuiStudio {
             const scenario = parsePreviewScenario(input.scenario);
             const renderBudget = new RenderBudget();
             let proposedGraph = buildGuiSourceGraph(proposedFiles, this.engine.indexFiles(proposedFiles));
-            const proposedAssetPatterns = referencedAssetPatternsForWindow(proposedGraph, input.windowName);
+            const proposedAssetPatterns = referencedAssetPatternsForWindow(proposedGraph, input.windowName, [], [scenario.language]);
             const exactProposedAssets = proposedAssetPatterns.length === 0
                 ? []
                 : await this.scanner.scan(workspace, {

package/dist/hoi4_agent_tools/gui/validators.js

@@ -509,7 +509,12 @@ function validateReferencesAndScript(graph, scene, diagnostics) {
     const selectedSpriteNames = new Set(scene.elements.flatMap(({ sprite }) => (sprite === undefined ? [] : [sprite.spriteName])));
     const selectedSpriteIds = new Set(graph.sprites.filter(({ name }) => selectedSpriteNames.has(name)).map(({ id }) => id));
     const selectedFontNames = new Set(scene.elements.flatMap(({ text }) => (text?.fontName === undefined ? [] : [text.fontName])));
-    const selectedFontIds = new Set(graph.fonts.filter(({ name }) => selectedFontNames.has(name)).map(({ id }) => id));
+    const sceneLanguage = scene.scenario.language.toLocaleLowerCase('en-US');
+    const selectedFontIds = new Set(graph.fonts
+        .filter(({ name, languages }) => selectedFontNames.has(name) &&
+        (languages.length === 0 ||
+            languages.some((language) => language.toLocaleLowerCase('en-US') === sceneLanguage)))
+        .map(({ id }) => id));
     const selectedManifestIds = new Set(graph.animationSources
         .filter(({ sprite }) => selectedSpriteNames.has(sprite))
         .map(({ id }) => id));

package/dist/hoi4_agent_tools/mcp/tools/gui.js

@@ -4,7 +4,7 @@ import { canonicalJson, compareCodeUnits, hashCanonical } from '../../core/canon
 import { renderDimensionViolation, RenderBudget, RENDER_MAX_DIMENSION, } from '../../core/render-budget.js';
 import { emptyServiceResult, ServiceError } from '../../core/result.js';
 import { SOURCE_MAX_BYTES } from '../../core/source/index.js';
-import { GuiHelperDocumentSchema, GuiPreviewScenarioSchema, GUI_TEXT_PACKAGE_MAX_FILES, ScriptedGuiStudio, compileGuiHelpers, } from '../../gui/index.js';
+import { GuiHelperDocumentSchema, GuiGeneratedScenarioOptionsSchema, GuiPreviewScenarioSchema, GUI_TEXT_PACKAGE_MAX_FILES, ScriptedGuiStudio, compileGuiHelpers, } from '../../gui/index.js';
 import { encodeGuiInspectionArtifact, projectGuiGraphForArtifact, } from '../../gui/inspection-artifact.js';
 import { workspaceIdSchema, workspaceRelativePathSchema } from '../../schemas/common.js';
 import { PACKAGE_VERSION } from '../../version.js';
@@ -92,6 +92,7 @@ const previewStateSchema = z.enum([
     'missing-localisation',
 ]);
 const compactGuiScenarioSchema = compactValidatedInputSchema(GuiPreviewScenarioSchema, `Complete GUI preview scenario: https://github.com/klimPaskov/hoi4-agent-tools/blob/v${PACKAGE_VERSION}/docs/gui.md`);
+const compactGeneratedScenarioOptionsSchema = compactValidatedInputSchema(GuiGeneratedScenarioOptionsSchema, `Options: https://github.com/klimPaskov/hoi4-agent-tools/blob/v${PACKAGE_VERSION}/docs/gui.md`);
 const compactGuiHelperSchema = compactValidatedInputSchema(GuiHelperDocumentSchema, `Complete GUI helper document: https://github.com/klimPaskov/hoi4-agent-tools/blob/v${PACKAGE_VERSION}/docs/gui.md`);
 const guiBaseInput = z
     .object({
@@ -106,6 +107,7 @@ const guiInspectInput = z
     windowName: z.string().min(1).max(256).optional(),
     scenario: compactGuiScenarioSchema.optional(),
     relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
+    generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
 })
     .strict()
     .superRefine((value, context) => {
@@ -122,6 +124,13 @@ const guiInspectInput = z
             message: 'relatedScenarios requires a window scenario',
         });
     }
+    if (value.generatedScenarios !== undefined && value.scenario === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['generatedScenarios'],
+            message: 'generatedScenarios requires a window scenario',
+        });
+    }
 });
 const resolutionSchema = z
     .object({
@@ -147,11 +156,11 @@ export function registerGuiTools(server, engine, context) {
     const studio = new ScriptedGuiStudio(engine);
     server.registerTool('hoi4.gui_inspect', {
         title: 'Inspect scripted GUI',
-        description: 'Inspect GUI, GFX, script, localisation, and animation sources. Window/scenario selectors add offline visual and interaction diagnostics.',
+        description: 'Inspect GUI sources and scenarios.',
         inputSchema: guiInspectInput,
         outputSchema: guiScanOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId: requestedWorkspaceId, windowName, scenario, relatedScenarios }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, windowName, scenario, relatedScenarios, generatedScenarios, }, extra) => {
         const workspaceId = await resolveServerWorkspaceId(engine, context, requestedWorkspaceId, extra.signal);
         try {
             const progress = progressReporter(extra);
@@ -166,6 +175,7 @@ export function registerGuiTools(server, engine, context) {
                     windowName,
                     scenario,
                     ...(relatedScenarios === undefined ? {} : { relatedScenarios }),
+                    generatedScenarios: generatedScenarios ?? {},
                     ...(context.principal === undefined ? {} : { principal: context.principal }),
                     signal: progress.signal,
                 });
@@ -285,6 +295,7 @@ export function registerGuiTools(server, engine, context) {
                 ...(input.relatedScenarios === undefined
                     ? {}
                     : { relatedScenarios: input.relatedScenarios }),
+                generatedScenarios: input.generatedScenarios ?? {},
                 ...(input.comparisonScenario === undefined
                     ? {}
                     : { comparisonScenario: input.comparisonScenario }),
@@ -333,10 +344,11 @@ export function registerGuiTools(server, engine, context) {
         states: z.array(previewStateSchema).max(14).optional(),
         resolutions: z.array(resolutionSchema).min(1).max(16).optional(),
         relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
+        generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
         comparisonScenario: compactGuiScenarioSchema.optional(),
     })
         .strict()
-        .superRefine(({ scenario, states, resolutions, relatedScenarios }, context) => {
+        .superRefine(({ scenario, states, resolutions, relatedScenarios, generatedScenarios }, context) => {
         const budget = new RenderBudget();
         try {
             const stateCount = states?.length ?? 14;
@@ -351,7 +363,12 @@ export function registerGuiTools(server, engine, context) {
             ]) {
                 budget.reserve(resolution.width, resolution.height, 'GUI resolution variant');
             }
-            const scenarioCount = 1 + (relatedScenarios?.length ?? 0);
+            const generatedCount = generatedScenarios?.enabled === false ? 0 : (generatedScenarios?.count ?? 1);
+            const scenarioCount = generatedCount === 0
+                ? 1 + (relatedScenarios?.length ?? 0)
+                : generatedCount +
+                    (generatedScenarios?.preservePlaceholder === false ? 0 : 1) +
+                    (relatedScenarios?.length ?? 0);
             const stateColumns = Math.min(3, Math.max(1, stateCount));
             const stateRows = Math.max(1, Math.ceil(stateCount / stateColumns));
             budget.reserve(stateColumns * 420, 46 + stateRows * 280, 'GUI state gallery');
@@ -374,7 +391,7 @@ export function registerGuiTools(server, engine, context) {
     });
     server.registerTool('hoi4.gui_render', {
         title: 'Render scripted GUI artifacts',
-        description: 'Render deterministic GUI review artifacts, named value-driven scenario variants, generic states, resolutions, click regions, hierarchy, comparisons, and layout diagnostics.',
+        description: 'Render GUI states, resolutions, generated or explicit scenarios, hierarchy, comparisons, and diagnostics.',
         inputSchema: renderInput,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '2.8.4';
+export const PACKAGE_VERSION = '2.8.6';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/gui.md

@@ -33,12 +33,31 @@ Inspection checks missing assets and localisation, invalid sizes, overlap, clipp
 
 The renderer resolves sprites and fonts through the complete mod, dependency, and installed-game load order. Mod windows therefore render ordinary vanilla sprites, tiled vanilla panels, progress bars, masked shields, button frames, and localisation icons such as `£command_power` without copying game assets into the mod. Case differences in GFX and font identifiers do not prevent a valid asset from resolving.
 
-Bitmap text uses the language-appropriate HOI4 font definition and its real glyph atlas. Header, serif, compact, typewriter, black, inverted, and other declared faces keep their own glyph shapes, native metrics, face colour, border colour, and language override. HOI4 localisation colour runs such as `§Y` and `§R` recolour those same native glyphs instead of switching to the tool font. The default language uses the base font rather than an unrelated language override, and the renderer recognizes installed-game atlases whose filename omits a page suffix declared by the matching `.fnt` file.
+Bitmap text uses the language-appropriate HOI4 font definition and its real glyph atlas. Header, serif, compact, typewriter, black, inverted, and other declared faces keep their own glyph shapes, native metrics, face colour, border colour, language override, and font-specific `textcolors` palette. HOI4 localisation colour runs such as `§Y` and `§R` multiply the selected palette colour into the native glyph pixels, preserving the atlas's sharp antialiasing and dark shadow pixels instead of flattening the glyph into a blurred monochrome mask or switching to the tool font. The default language uses the base font rather than an unrelated language override, and the renderer recognizes installed-game atlases whose filename omits a page suffix declared by the matching `.fnt` file.
 
 Layout follows Clausewitz orientation and element-origin anchors, including `CENTER_LEFT`, `CENTER_RIGHT`, `CENTER_UP`, `CENTER_DOWN`, `origo`, `centerposition`, inherited container coordinate origins, local scale, and both `%` and `%%` relative dimensions. Text boxes use native font metrics together with `maxWidth`, `maxHeight`, alignment, wrapping, and `fixedsize` clipping. Cornered tile sprites use fixed nine-slice borders and optional center tiling; progress bars composite their filled and background textures; masked shields composite their background and mask textures.
 
 Scripted-GUI composition follows `parent_scripted_gui` chains even when the linked child window is a top-level sibling in the `.gui` file. Literal `always = yes` and `always = no` visibility and click-enabled blocks are applied automatically. A scenario's `values` object supplies concrete runtime values in one place: variable names resolve numeric text, scripted-localisation names resolve dynamic labels, a progress-bar element name sets its fill value, and element keys ending in `.image`, `.frame`, `.x`, `.y`, `.visible`, or `.enabled` update that visual property. Scripted-GUI property expressions such as `image = "[GetMeterSprite]"` or `x = meter_fill_width` consume matching scenario values automatically. Dynamic lists instantiate their declared `entry_container` or `country_scope_entry_container`; each scenario row can select the country template with `countryScope`, choose an explicit `entryContainer`, and provide row-scoped text, image, frame, position, visibility, and enabled values.
 
+`hoi4.gui_inspect` and `hoi4.gui_render` generate a plausible seeded runtime scenario by default. The generator follows the complete `parent_scripted_gui` surface, discovers numeric and text tokens in GUI localisation and scripted-GUI properties, chooses real scripted-localisation text and sprite candidates, applies simple source thresholds, fills meters within their declared ranges, populates dynamic lists with coherent rows, selects one overlapping tab pane, keeps active and idle controls mutually exclusive, and leaves values explicitly supplied by the caller unchanged. Normal controls and animation frames remain stable unless variation is explicitly requested. Every explicit `relatedScenarios` entry is rendered beside the generated view.
+
+Generation is reproducible. Set `generatedScenarios.seed` to any stable string for an exact rerun, use `count` for several plausible versions, or configure numeric bounds, integer or decimal values, list row bounds, text samples, visibility probability, and state variation. The generated view is the default. Set `enabled` to `false` when only the supplied placeholder scenario should render, or set `preservePlaceholder` to `true` to include the placeholder beside generated scenarios.
+
+```json
+{
+  "generatedScenarios": {
+    "seed": "chaos-meter-review",
+    "count": 3,
+    "numericMinimum": 0,
+    "numericMaximum": 100,
+    "listRowsMinimum": 2,
+    "listRowsMaximum": 8,
+    "trueProbability": 0.75,
+    "textSamples": ["Stable", "Escalating", "Critical"]
+  }
+}
+```
+
 Preview scenarios can include exact layout expectations:
 
 ```json
@@ -70,10 +89,10 @@ GUI rewrites keep complete validation evidence in a linked JSON resource and ret
 
 Large inspections, renders, and rewrites send periodic MCP progress heartbeats while a service stage is still running. Clients that request progress can reset their idle request timer from these notifications; there is no 180-second GUI operation limit in the server, and cancellation still follows the request signal.
 
-## Offline preview limits
+## Scenario fidelity
 
 The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.
 
-Unresolved numeric runtime values such as `[?variable|format]` render as `[X]`. Unresolved text-returning scripted or scoped localisation such as `[GetStatusText]`, `[FROM.GetName]`, and `[?leader_scope.GetName]` renders as `[dynamic_loc]`. Put `variable` or `GetStatusText` in the scenario's `values` object when the exact value matters; the same scenario can set the related meter or state-dependent controls. Supported HOI4 `§` localisation colour controls are applied to preview text and `§!` restores the default colour.
+The generated primary view replaces discovered numeric and text runtime tokens with plausible values. Set `generatedScenarios.preservePlaceholder` to `true`, or disable generation, when the same run should also show unresolved numeric values such as `[?variable|format]` as `[X]` and unresolved text-returning scripted or scoped localisation such as `[GetStatusText]`, `[FROM.GetName]`, and `[?leader_scope.GetName]` as `[dynamic_loc]`. Put `variable` or `GetStatusText` in the supplied scenario's `values` object when an exact value matters; explicit values always take precedence over generated ones and can drive the related meter or state-dependent controls. Supported HOI4 `§` localisation colour controls use the active font's palette and `§!` restores the face colour.
 
 A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Frame-sheet animation, nine-slice tiling, progress composition, masking, and the primary and secondary textures referenced by vanilla GFX definitions render offline. Engine shader programs, hardcoded controls, and dynamic values that are not supplied by a scenario remain fidelity-report entries; an unexecuted shader never hides its resolved base texture.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.8.4",
+  "version": "2.8.6",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/continuous-focus-palette.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/custom-weighted-pool.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/event-feature-manifest.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/event-feature-manifest.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-plan.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/focus-plan.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-planning-sidecar.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-animation-source.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/gui-animation-source.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-helper.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/gui-helper.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-scenario.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/gui-scenario.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/map-operation.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.4/schemas/map-operation.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.6/schemas/map-operation.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "oneOf": [
     {