hoi4-agent-tools 2.8.3 → 2.8.5

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 No unreleased changes.
 
+## 2.8.5 - 2026-08-28
+
+- Render bitmap-font face and localisation colours through alpha masks, including black source atlases, and load exact per-font HOI4 `textcolors` palettes.
+- Generate configurable seeded GUI scenarios with plausible dynamic text, numeric values, meters, lists, visibility, control states, and animation frames while retaining explicit values and the unresolved placeholder view.
+
+## 2.8.4 - 2026-08-28
+
+- Render each declared HOI4 font face with its own glyph atlas, native metrics, face colour, border colour, and inherited language-override styling.
+- Keep native HOI4 bitmap or outline glyphs when localisation colour markup changes part of a line instead of replacing the line with the generic tool font.
+
 ## 2.8.3 - 2026-08-27
 
 - Centered native button labels when HOI4 GUI source uses `text =` instead of `buttonText =`, matching the in-game horizontal and vertical alignment inside button frames.

package/README.md

@@ -31,31 +31,31 @@ Paste the printed Codex or generic global-install entry into your MCP client, th
 
 ## Tools
 
-| Tool                        | Purpose                                                                                  |
-| --------------------------- | ---------------------------------------------------------------------------------------- |
-| `hoi4.focus_inspect`        | Read focus trees, continuous-focus placement, and structural or reference problems.      |
-| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                        |
-| `hoi4.focus_raster`         | Produce a high-fidelity PNG review with decoded source icons.                            |
-| `hoi4.focus_rewrite`        | Create or update a focus tree.                                                           |
-| `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                     |
-| `hoi4.gui_render`           | Render GUI scenario variants, states, resolutions, hierarchy, and layout diagnostics.    |
-| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                   |
-| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.      |
-| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.   |
-| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.    |
-| `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                 |
-| `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.  |
-| `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                          |
-| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                  |
-| `hoi4.tech_render`          | Render source layouts, dependency paths, unlocks, grants, metadata, and asset coverage.  |
-| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.     |
-| `hoi4.probability_inspect`  | Locate weighted logic and discover compatible adapters, candidates, and required inputs. |
-| `hoi4.probability_evaluate` | Evaluate exact values, probabilities, timing, bounds, and unresolved inputs.             |
-| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.        |
-| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                 |
-| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.         |
-| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                    |
-| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.        |
+| Tool                        | Purpose                                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------------------- |
+| `hoi4.focus_inspect`        | Read focus trees, continuous-focus placement, and structural or reference problems.       |
+| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                         |
+| `hoi4.focus_raster`         | Produce a high-fidelity PNG review with decoded source icons.                             |
+| `hoi4.focus_rewrite`        | Create or update a focus tree.                                                            |
+| `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                      |
+| `hoi4.gui_render`           | Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics. |
+| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                    |
+| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.       |
+| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.    |
+| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.     |
+| `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                  |
+| `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.   |
+| `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                           |
+| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                   |
+| `hoi4.tech_render`          | Render source layouts, dependency paths, unlocks, grants, metadata, and asset coverage.   |
+| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.      |
+| `hoi4.probability_inspect`  | Locate weighted logic and discover compatible adapters, candidates, and required inputs.  |
+| `hoi4.probability_evaluate` | Evaluate exact values, probabilities, timing, bounds, and unresolved inputs.              |
+| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.         |
+| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                  |
+| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.          |
+| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                     |
+| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.         |
 
 Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, follow the `continuationUri` returned in `_meta` until it is `null`; clients may also request byte ranges with `?offset=<bytes>&length=<bytes>`.
 

package/dist/hoi4_agent_tools/gui/assets.js

@@ -180,6 +180,31 @@ export class GuiAssetCatalog {
                     definition.languages.length === 0))
                 this.fontDefinitions.set(key, definition);
         }
+        const baseDefinitions = new Map();
+        for (const definition of graph.fonts) {
+            if (definition.override || definition.languages.length > 0)
+                continue;
+            const key = definition.name.toLocaleLowerCase('en-US');
+            if (!baseDefinitions.has(key))
+                baseDefinitions.set(key, definition);
+        }
+        for (const [key, definition] of this.fontDefinitions) {
+            if (!definition.override)
+                continue;
+            const base = baseDefinitions.get(key);
+            if (base === undefined)
+                continue;
+            this.fontDefinitions.set(key, {
+                ...definition,
+                ...(definition.colour === undefined && base.colour !== undefined
+                    ? { colour: base.colour }
+                    : {}),
+                ...(definition.borderColour === undefined && base.borderColour !== undefined
+                    ? { borderColour: base.borderColour }
+                    : {}),
+                textColours: { ...base.textColours, ...definition.textColours },
+            });
+        }
     }
     resolveFile(assetPath, relativeTo) {
         const normalized = normalizeAssetPath(assetPath);
@@ -558,11 +583,23 @@ export class GuiAssetCatalog {
                     return undefined;
                 this.budget.reserveRasterOperation(`gui-bmfont-glyph:${key}`, `GUI BMFont glyph rasterization U+${codePoint.toString(16).toUpperCase()}`);
                 this.budget.reserve(metric.width, metric.height, `GUI BMFont glyph U+${codePoint.toString(16).toUpperCase()}`, { maximumPixels: RENDER_MAX_DECODED_PIXELS });
-                const png = await sharp(raster.data, {
+                const extracted = await sharp(raster.data, {
                     raw: { width: raster.width, height: raster.height, channels: 4 },
                     limitInputPixels: RENDER_MAX_DECODED_PIXELS,
                 })
                     .extract({ left: metric.x, top: metric.y, width: metric.width, height: metric.height })
+                    .ensureAlpha()
+                    .raw()
+                    .toBuffer({ resolveWithObject: true });
+                for (let index = 0; index < extracted.data.length; index += 4) {
+                    extracted.data[index] = 255;
+                    extracted.data[index + 1] = 255;
+                    extracted.data[index + 2] = 255;
+                }
+                const png = await sharp(extracted.data, {
+                    raw: { width: extracted.info.width, height: extracted.info.height, channels: 4 },
+                    limitInputPixels: RENDER_MAX_DECODED_PIXELS,
+                })
                     .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
                     .toBuffer();
                 return {

package/dist/hoi4_agent_tools/gui/index.js

@@ -6,6 +6,7 @@ export * from './layout.js';
 export * from './limits.js';
 export * from './renderer.js';
 export * from './scenario.js';
+export * from './scenario-generator.js';
 export * from './source-graph.js';
 export * from './source-patch.js';
 export * from './studio.js';

package/dist/hoi4_agent_tools/gui/layout.js

@@ -26,23 +26,32 @@ function scalarString(value) {
 }
 const defaultTextColour = '#f5f2e8';
 const hoi4TextColours = {
-    B: '#4aa3df',
-    C: '#55d6d6',
-    G: '#56b870',
-    H: '#e7b454',
-    L: '#9aa7b3',
-    M: '#d16bd4',
-    O: '#e58b3c',
-    R: '#e05a5a',
-    T: '#4bc6b9',
-    W: defaultTextColour,
-    Y: '#f1c75b',
-    b: '#4aa3df',
-    g: '#87939e',
+    C: '#23ceff',
+    L: '#c3b091',
+    W: '#ffffff',
+    B: '#0000ff',
+    G: '#009f03',
+    R: '#ff3232',
+    b: '#000000',
+    g: '#b0b0b0',
+    Y: '#ffbd00',
+    H: '#ffbd00',
+    T: '#ffffff',
+    O: '#ff7019',
+    '0': '#cb00cb',
+    '1': '#8078d3',
+    '2': '#5170f3',
+    '3': '#518fdc',
+    '4': '#5abee7',
+    '5': '#3fb5c2',
+    '6': '#77ccba',
+    '7': '#99d199',
+    '8': '#d1d175',
+    '9': '#d1a675',
 };
 const inlineIconMarkerStart = 0xe000;
 const inlineIconMarkerEnd = 0xf8ff;
-function visibleHoiText(value) {
+function visibleHoiText(value, fontTextColours = {}) {
     const characters = [];
     const colours = [];
     const inlineIcons = [];
@@ -53,7 +62,7 @@ function visibleHoiText(value) {
         const next = value[index + 1];
         if (character === '\u00a7' && next !== undefined && /^[A-Za-z0-9!]$/u.test(next)) {
             hasColourMarkup = true;
-            colour = next === '!' ? undefined : hoi4TextColours[next];
+            colour = next === '!' ? undefined : (fontTextColours[next] ?? hoi4TextColours[next]);
             index += 1;
             continue;
         }
@@ -446,7 +455,7 @@ function wrapText(catalog, fontName, text, colours, fontSize, maximumWidth, work
         missingGlyphs: [...missingGlyphs].sort((a, b) => a - b),
     };
 }
-function colourRunsForLine(catalog, fontName, line, colours, fontSize, work, inlineIcons = new Map()) {
+function colourRunsForLine(catalog, fontName, line, colours, fontSize, work, inlineIcons = new Map(), defaultColour = defaultTextColour) {
     if (!colours.some((colour) => colour !== undefined) || line.length === 0)
         return [];
     const runs = [];
@@ -459,11 +468,11 @@ function colourRunsForLine(catalog, fontName, line, colours, fontSize, work, inl
             start += 1;
             continue;
         }
-        const colour = colours[start] ?? defaultTextColour;
+        const colour = colours[start] ?? defaultColour;
         let end = start + 1;
         while (end < line.length &&
             !inlineIcons.has(line[end] ?? '') &&
-            (colours[end] ?? defaultTextColour) === colour)
+            (colours[end] ?? defaultColour) === colour)
             end += 1;
         const text = line.slice(start, end);
         work.spendTextLayout('localisation colour-run measurement');
@@ -739,10 +748,11 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             displayText = `${displayText} — ${displayText} — ${displayText}`;
         if (state === 'missing-localisation')
             displayText = `\u00a7R${rawText}_MISSING\u00a7!`;
-        const visibleText = visibleHoiText(displayText);
+        const fontName = scalarString(property(definition.attributes, 'font', 'buttonFont'));
+        const fontDefinition = fontName === undefined ? undefined : catalog.fontDefinition(fontName);
+        const visibleText = visibleHoiText(displayText, fontDefinition?.textColours);
         displayText = visibleText.text;
         context.work.admitText(displayText, `GUI text for ${definition.name}`);
-        const fontName = scalarString(property(definition.attributes, 'font', 'buttonFont'));
         const resolvedFontMetrics = catalog.resolvedFontMetrics(fontName);
         const explicitFontSize = scalarNumber(property(definition.attributes, 'fontSize'), 16);
         const fontSize = explicitFontSize ??
@@ -792,7 +802,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             inlineIcons.push(...shaped.icons);
         }
         const colourRuns = visibleText.hasColourMarkup
-            ? wrapped.lines.map((line, index) => colourRunsForLine(catalog, fontName, line, wrapped.colourLines[index] ?? [], fontSize * scale, context.work, resolvedInlineIcons))
+            ? wrapped.lines.map((line, index) => colourRunsForLine(catalog, fontName, line, wrapped.colourLines[index] ?? [], fontSize * scale, context.work, resolvedInlineIcons, fontDefinition?.colour ?? defaultTextColour))
             : undefined;
         const maximumLineWidth = wrapped.widths.reduce((maximum, value) => Math.max(maximum, value), 0);
         if (width === 0)
@@ -812,6 +822,10 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             metricSource: wrapped.metricSource,
             ...alignment(definition.attributes, embeddedButtonText),
             ...(fontName === undefined ? {} : { fontName }),
+            ...(fontDefinition?.colour === undefined ? {} : { colour: fontDefinition.colour }),
+            ...(fontDefinition?.borderColour === undefined
+                ? {}
+                : { borderColour: fontDefinition.borderColour }),
             glyphLines,
             overflowX: width > 0 && measuredWidth > width + 0.01,
             overflowY: height > 0 && measuredHeight > height + 0.01,
@@ -824,6 +838,8 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             addFidelity(fidelity, 'approximated', 'font_metrics', `No supplied font metrics for ${fontName ?? '<default>'}.`, definition);
         else
             addFidelity(fidelity, 'modelled', 'font_metrics', `${wrapped.metricSource} metrics for ${fontName ?? '<default>'}.`, definition);
+        if (fontDefinition?.colour !== undefined || fontDefinition?.borderColour !== undefined)
+            addFidelity(fidelity, 'modelled', 'font_definition_style', `Font ${fontDefinition.name} uses its declared face and colour styling.`, definition);
         const missingGlyphs = [
             ...new Set([...wrapped.missingGlyphs, ...glyphLines.flatMap((line) => line.missingGlyphs)]),
         ].slice(0, GUI_TEXT_MAX_MISSING_GLYPH_SAMPLES);

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -62,6 +62,22 @@ function sceneGlyphDefinitions(scene) {
             .map(([key, glyph]) => `<image id="${bitmapDefinitionId(key)}" width="${finite(glyph.width)}" height="${finite(glyph.height)}" href="${glyph.dataUri}" preserveAspectRatio="none"/>`),
     ].join('');
 }
+function bitmapTintMarkup(id, colour, glyphs, rect) {
+    return `<defs><mask id="${id}" maskUnits="userSpaceOnUse" maskContentUnits="userSpaceOnUse" style="mask-type:alpha" ${rectAttributes(rect)}><g>${glyphs}</g></mask></defs><rect ${rectAttributes(rect)} fill="${colour}" mask="url(#${id})"/>`;
+}
+function actualGlyphMarkup(glyphLine, originX, baseline, horizontalScale) {
+    if (glyphLine.source === 'fontkit-path')
+        return glyphLine.glyphs
+            .filter((glyph) => glyph.kind === 'outline')
+            .map((glyph) => `<use href="#${outlineDefinitionId(glyph.key)}" transform="translate(${finite(originX + glyph.x * horizontalScale)} ${finite(baseline + glyph.y)}) scale(${finite(glyph.scale * horizontalScale)} ${finite(-glyph.scale)})"/>`)
+            .join('');
+    if (glyphLine.source === 'bmfont-atlas')
+        return glyphLine.glyphs
+            .filter((glyph) => glyph.kind === 'bitmap')
+            .map((glyph) => `<use href="#${bitmapDefinitionId(glyph.key)}" transform="translate(${finite(originX + glyph.x * horizontalScale)} ${finite(baseline + glyph.y - glyphLine.baseline)}) scale(${finite(horizontalScale)} 1)"/>`)
+            .join('');
+    return '';
+}
 function renderText(element, toolText) {
     const text = element.text;
     if (text === undefined || text.lines.length === 0)
@@ -102,6 +118,30 @@ function renderText(element, toolText) {
         })
             .join('');
         const colourRuns = text.colourRuns?.[index] ?? [];
+        if (colourRuns.length > 0 &&
+            glyphLine !== undefined &&
+            glyphLine.source !== 'deterministic-fallback') {
+            const definitions = [];
+            const renderedRuns = colourRuns.map((run, runIndex) => {
+                const key = `${element.id}:${index}:${runIndex}:${run.colour}`;
+                const clipId = `gui-font-run-clip-${sha256Bytes(key).slice(0, 20)}`;
+                const runX = originX + run.offsetX * horizontalScale;
+                definitions.push(`<clipPath id="${clipId}"><rect x="${finite(runX - 0.25)}" y="${finite(lineTop)}" width="${finite(run.width * horizontalScale + 0.5)}" height="${finite(text.lineHeight)}"/></clipPath>`);
+                const glyphs = actualGlyphMarkup(glyphLine, originX, baseline, horizontalScale);
+                if (glyphLine.source === 'bmfont-atlas') {
+                    const maskId = `gui-font-mask-${sha256Bytes(key).slice(0, 20)}`;
+                    const runRect = {
+                        x: runX - 0.25,
+                        y: lineTop,
+                        width: run.width * horizontalScale + 0.5,
+                        height: text.lineHeight,
+                    };
+                    return `<g clip-path="url(#${clipId})" data-font-colour="${run.colour}">${bitmapTintMarkup(maskId, run.colour, glyphs, runRect)}</g>`;
+                }
+                return `<g clip-path="url(#${clipId})" fill="${run.colour}" stroke="${text.borderColour ?? '#12151a'}" data-font-colour="${run.colour}">${glyphs}</g>`;
+            });
+            return `<g data-hoi4-colour-runs="true" data-font-sha256="${glyphLine.sourceHash}"><defs>${definitions.join('')}</defs>${renderedRuns.join('')}${inlineIconMarkup}</g>`;
+        }
         if (colourRuns.length > 0) {
             return `<g data-hoi4-colour-runs="true">${colourRuns
                 .map((run) => toolText.render(run.text, {
@@ -109,31 +149,30 @@ function renderText(element, toolText) {
                 y: baseline,
                 fontSize: text.fontSize,
                 fill: run.colour,
-                stroke: '#12151a',
+                stroke: text.borderColour ?? '#12151a',
                 strokeWidth: 0.6,
                 ...(run.width > 0 ? { targetWidth: run.width * horizontalScale } : {}),
             }))
                 .join('')}${inlineIconMarkup}</g>`;
         }
         if (glyphLine?.source === 'fontkit-path') {
-            return `<g data-font-sha256="${glyphLine.sourceHash}">${glyphLine.glyphs
-                .filter((glyph) => glyph.kind === 'outline')
-                .map((glyph) => `<use href="#${outlineDefinitionId(glyph.key)}" transform="translate(${finite(originX + glyph.x * horizontalScale)} ${finite(baseline + glyph.y)}) scale(${finite(glyph.scale * horizontalScale)} ${finite(-glyph.scale)})"/>`)
-                .join('')}${inlineIconMarkup}</g>`;
+            return `<g data-font-sha256="${glyphLine.sourceHash}" fill="${text.colour ?? '#f5f2e8'}" stroke="${text.borderColour ?? '#12151a'}" data-font-colour="${text.colour ?? '#f5f2e8'}">${actualGlyphMarkup(glyphLine, originX, baseline, horizontalScale)}${inlineIconMarkup}</g>`;
         }
         if (glyphLine?.source === 'bmfont-atlas') {
-            return `<g data-font-sha256="${glyphLine.sourceHash}">${glyphLine.glyphs
-                .filter((glyph) => glyph.kind === 'bitmap')
-                .map((glyph) => `<use href="#${bitmapDefinitionId(glyph.key)}" transform="translate(${finite(originX + glyph.x * horizontalScale)} ${finite(baseline + glyph.y - glyphLine.baseline)}) scale(${finite(horizontalScale)} 1)"/>`)
-                .join('')}${inlineIconMarkup}</g>`;
+            const glyphs = actualGlyphMarkup(glyphLine, originX, baseline, horizontalScale);
+            if (text.colour === undefined)
+                return `<g data-font-sha256="${glyphLine.sourceHash}">${glyphs}${inlineIconMarkup}</g>`;
+            const maskId = `gui-font-mask-${sha256Bytes(`${element.id}:${index}:${text.colour}`).slice(0, 20)}`;
+            const lineRect = { x: originX, y: lineTop, width, height: text.lineHeight };
+            return `<g data-font-sha256="${glyphLine.sourceHash}" data-font-colour="${text.colour}">${bitmapTintMarkup(maskId, text.colour, glyphs, lineRect)}${inlineIconMarkup}</g>`;
         }
         const visibleLine = line.replace(/[\uE000-\uF8FF]/gu, ' ');
         return `<g>${toolText.render(visibleLine, {
             x: originX,
             y: baseline,
             fontSize: text.fontSize,
-            fill: '#f5f2e8',
-            stroke: '#12151a',
+            fill: text.colour ?? '#f5f2e8',
+            stroke: text.borderColour ?? '#12151a',
             strokeWidth: 0.6,
             ...(width > 0 ? { targetWidth: width } : {}),
         })}${inlineIconMarkup}</g>`;

package/dist/hoi4_agent_tools/gui/scenario-generator.js

@@ -0,0 +1,223 @@
+import { sha256Bytes } from '../core/canonical.js';
+import { parsePreviewScenario } from './scenario.js';
+const countryNames = ['Germany', 'France', 'Poland', 'Italy', 'Brazil', 'India', 'Canada'];
+const countryAdjectives = [
+    'German',
+    'French',
+    'Polish',
+    'Italian',
+    'Brazilian',
+    'Indian',
+    'Canadian',
+];
+const leaderNames = ['Anna Keller', 'Michael Byrne', 'Elena Rossi', 'Jan Kowalski', 'Rafael Silva'];
+const variedStates = [
+    'normal',
+    'selected',
+    'active',
+    'warning',
+    'disabled',
+    'completed',
+];
+class ScenarioRandom {
+    #state;
+    constructor(seed) {
+        this.#state = Number.parseInt(sha256Bytes(seed).slice(0, 8), 16) || 0x6d2b_79f5;
+    }
+    next() {
+        this.#state = (this.#state + 0x6d2b_79f5) >>> 0;
+        let value = this.#state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+    }
+    boolean(probability) {
+        return this.next() < probability;
+    }
+    integer(minimum, maximum) {
+        return Math.floor(this.next() * (maximum - minimum + 1)) + minimum;
+    }
+    pick(values) {
+        return values[Math.min(values.length - 1, Math.floor(this.next() * values.length))];
+    }
+}
+function relevantElements(graph, windowName) {
+    const root = graph.elements.find((element) => element.parentId === undefined && element.name === windowName);
+    if (root === undefined)
+        return graph.elements.filter(({ name }) => name === windowName);
+    const byId = new Map(graph.elements.map((element) => [element.id, element]));
+    const pending = [root.id];
+    const selected = [];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const id = pending.pop();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const element = byId.get(id);
+        if (element === undefined)
+            continue;
+        selected.push(element);
+        pending.push(...element.childIds);
+    }
+    return selected;
+}
+function stringsIn(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (typeof value !== 'object')
+        return [];
+    return Object.values(value).flatMap(stringsIn);
+}
+function localisationText(graph, language, key) {
+    return graph.localisation.find((entry) => entry.language === language && entry.key === key)
+        ?.value;
+}
+function sourceTexts(graph, elements, language, scripted) {
+    const values = elements.flatMap((element) => Object.values(element.attributes).flatMap(stringsIn));
+    const propertyValues = scripted.flatMap((definition) => definition.propertyDefinitions.flatMap((property) => Object.values(property.attributes).flatMap(stringsIn)));
+    return [...values, ...propertyValues].flatMap((value) => [
+        value,
+        localisationText(graph, language, value) ?? '',
+    ]);
+}
+function dynamicTokens(texts) {
+    const numeric = new Set();
+    const textual = new Set();
+    for (const text of texts) {
+        for (const match of text.matchAll(/\[\?([^\]|]+)(?:\|[^\]]+)?\]/gu)) {
+            const key = match[1] ?? '';
+            if (/(?:^|\.)Get[A-Za-z0-9_]+$/u.test(key))
+                textual.add(key);
+            else
+                numeric.add(key);
+        }
+        for (const match of text.matchAll(/\[([A-Za-z][A-Za-z0-9_.:-]+)\]/gu)) {
+            const key = match[1] ?? '';
+            if (key !== 'X' && key !== 'dynamic_loc')
+                textual.add(key);
+        }
+    }
+    return {
+        numeric: [...numeric].sort(),
+        textual: [...textual].sort(),
+    };
+}
+function plausibleText(key, random, samples) {
+    const lower = key.toLocaleLowerCase('en-US');
+    if (lower.includes('adjective'))
+        return random.pick(countryAdjectives);
+    if (lower.includes('leader') || lower.includes('character'))
+        return random.pick(leaderNames);
+    if (lower.includes('country') || lower.endsWith('getname') || lower.includes('.getname'))
+        return random.pick(countryNames);
+    return random.pick(samples);
+}
+function generatedNumber(options, random) {
+    const value = options.numericMinimum + random.next() * (options.numericMaximum - options.numericMinimum);
+    return options.integerValues ? Math.round(value) : Math.round(value * 100) / 100;
+}
+function setIfMissing(target, key, value) {
+    target[key] ??= value;
+    const shortKey = key.slice(key.lastIndexOf('.') + 1);
+    target[shortKey] ??= value;
+}
+function generatedRows(count, random, options) {
+    return Array.from({ length: count }, (_unused, index) => {
+        const name = plausibleText('GetName', random, options.textSamples);
+        const value = generatedNumber(options, random);
+        return {
+            index: index + 1,
+            id: index + 1,
+            label: name,
+            name,
+            GetName: name,
+            value,
+            amount: value,
+            percentage: Math.max(0, Math.min(100, value)),
+            selected: index === 0,
+            enabled: random.boolean(options.trueProbability),
+        };
+    });
+}
+export function generateGuiPreviewScenarios(graph, windowName, base, options) {
+    if (!options.enabled)
+        return [];
+    const elements = relevantElements(graph, windowName);
+    const scripted = graph.scriptedGuis.filter((definition) => definition.windowName === windowName || definition.parentWindowName === windowName);
+    const tokens = dynamicTokens(sourceTexts(graph, elements, base.language, scripted));
+    const dynamicLists = [...new Set(scripted.flatMap(({ dynamicLists }) => dynamicLists))].sort();
+    const visibilityTargets = new Set(scripted.flatMap((definition) => definition.propertyDefinitions
+        .filter((property) => Object.keys(property.attributes).some((key) => key.toLocaleLowerCase('en-US') === 'visible'))
+        .map(({ elementName }) => elementName)));
+    const enabledTargets = new Set(scripted.flatMap((definition) => [
+        ...definition.triggerDefinitions.map(({ elementName }) => elementName),
+        ...definition.propertyDefinitions
+            .filter((property) => Object.keys(property.attributes).some((key) => key.toLocaleLowerCase('en-US') === 'enabled'))
+            .map(({ elementName }) => elementName),
+    ]));
+    const spritesByName = new Map(graph.sprites.map((sprite) => [sprite.name.toLocaleLowerCase('en-US'), sprite]));
+    const sourceSeed = options.seed === 'auto' ? `${windowName}:${base.id}:${hashSourceGraph(graph)}` : options.seed;
+    return Array.from({ length: options.count }, (_unused, scenarioIndex) => {
+        const random = new ScenarioRandom(`${sourceSeed}:${scenarioIndex}`);
+        const values = { ...base.values };
+        const lists = Object.fromEntries(Object.entries(base.lists).map(([key, rows]) => [key, rows.map((row) => ({ ...row }))]));
+        const visibility = { ...base.visibility };
+        const elementStates = { ...base.elementStates };
+        const selectedFrames = { ...base.selectedFrames };
+        for (const key of tokens.numeric)
+            setIfMissing(values, key, generatedNumber(options, random));
+        for (const key of tokens.textual)
+            setIfMissing(values, key, plausibleText(key, random, options.textSamples));
+        for (const element of elements) {
+            if (values[element.name] === undefined && /progressbar/iu.test(element.elementType))
+                values[element.name] = generatedNumber(options, random);
+            if (visibilityTargets.has(element.name) && visibility[element.name] === undefined)
+                visibility[element.name] =
+                    options.visibility === 'show-all' || random.boolean(options.trueProbability);
+            elementStates[element.name] ??= enabledTargets.has(element.name)
+                ? random.boolean(options.trueProbability)
+                    ? options.elementStates === 'normal'
+                        ? 'normal'
+                        : random.pick(variedStates)
+                    : 'disabled'
+                : options.elementStates === 'normal'
+                    ? 'normal'
+                    : random.pick(variedStates);
+            const spriteName = [
+                element.attributes.spriteType,
+                element.attributes.quadTextureSprite,
+                element.attributes.background,
+            ].find((candidate) => typeof candidate === 'string');
+            const frameCount = spriteName === undefined
+                ? 1
+                : (spritesByName.get(spriteName.toLocaleLowerCase('en-US'))?.frameCount ?? 1);
+            if (Number.isFinite(frameCount) &&
+                frameCount > 1 &&
+                selectedFrames[element.name] === undefined)
+                selectedFrames[element.name] = random.integer(0, Math.trunc(frameCount) - 1);
+        }
+        for (const listName of dynamicLists) {
+            if (lists[listName] !== undefined)
+                continue;
+            const count = random.integer(options.listRowsMinimum, options.listRowsMaximum);
+            lists[listName] = generatedRows(count, random, options);
+        }
+        return parsePreviewScenario({
+            ...base,
+            id: `${base.id}-${options.idPrefix}-${scenarioIndex + 1}`,
+            description: `Generated plausible scenario ${scenarioIndex + 1} (seed ${sourceSeed})`,
+            values,
+            lists,
+            visibility,
+            elementStates,
+            selectedFrames,
+        });
+    });
+}
+function hashSourceGraph(graph) {
+    return sha256Bytes(Object.entries(graph.sourceHashes)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([path, hash]) => `${path}:${hash}`)
+        .join('\n'));
+}

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -193,9 +193,53 @@ export const GuiPreviewScenarioSchema = z.preprocess((input) => {
     assertGuiScenarioInputBudget(input);
     return input;
 }, GuiPreviewScenarioBodySchema);
+export const GuiGeneratedScenarioOptionsSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    count: z.number().int().min(1).max(16).default(1),
+    seed: z.string().min(1).max(256).default('auto'),
+    idPrefix: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u)
+        .default('generated'),
+    preservePlaceholder: z.boolean().default(true),
+    numericMinimum: z.number().min(-1_000_000_000).max(1_000_000_000).default(0),
+    numericMaximum: z.number().min(-1_000_000_000).max(1_000_000_000).default(100),
+    integerValues: z.boolean().default(true),
+    listRowsMinimum: z.number().int().min(0).max(100).default(1),
+    listRowsMaximum: z.number().int().min(0).max(100).default(5),
+    trueProbability: z.number().min(0).max(1).default(0.7),
+    visibility: z.enum(['show-all', 'varied']).default('varied'),
+    elementStates: z.enum(['normal', 'varied']).default('normal'),
+    textSamples: z
+        .array(z.string().min(1).max(128))
+        .min(1)
+        .max(64)
+        .default(['Operational', 'Ready', 'Stable', 'Available', 'In Progress']),
+})
+    .strict()
+    .superRefine((options, context) => {
+    if (options.numericMaximum < options.numericMinimum)
+        context.addIssue({
+            code: 'custom',
+            path: ['numericMaximum'],
+            message: 'numericMaximum must be greater than or equal to numericMinimum',
+        });
+    if (options.listRowsMaximum < options.listRowsMinimum)
+        context.addIssue({
+            code: 'custom',
+            path: ['listRowsMaximum'],
+            message: 'listRowsMaximum must be greater than or equal to listRowsMinimum',
+        });
+});
 export function parsePreviewScenario(input) {
     return GuiPreviewScenarioSchema.parse(input);
 }
 export function defaultPreviewScenario(id = 'default') {
     return parsePreviewScenario({ id });
 }
+export function parseGeneratedScenarioOptions(input) {
+    return GuiGeneratedScenarioOptionsSchema.parse(input);
+}

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

@@ -188,6 +188,35 @@ function boolScalar(block, ...keys) {
         return false;
     return undefined;
 }
+function paradoxColour(value) {
+    if (value === undefined)
+        return undefined;
+    const match = /^0x([0-9a-f]{8})$/iu.exec(value.trim());
+    if (match === null)
+        return undefined;
+    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)
@@ -425,6 +454,9 @@ function indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites,
                     const languages = childBlocks(child, 'languages').flatMap((languageBlock) => languageBlock.entries
                         .filter((entry) => entry.type === 'scalar')
                         .map((entry) => entry.value));
+                    const colour = paradoxColour(firstScalarInsensitive(child, 'color', 'colour'));
+                    const borderColour = paradoxColour(firstScalarInsensitive(child, 'border_color', 'borderColor', 'border_colour'));
+                    const textColours = textColoursFrom(child);
                     const id = deterministicId('gui_font', { path: file.displayPath, name });
                     const font = {
                         id,
@@ -435,6 +467,9 @@ function indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites,
                         override: assignment.key.value === 'bitmapfont_override',
                         languages,
                         assetPaths,
+                        ...(colour === undefined ? {} : { colour }),
+                        ...(borderColour === undefined ? {} : { borderColour }),
+                        ...(Object.keys(textColours).length === 0 ? {} : { textColours }),
                         rawSource: raw(document, assignment),
                     };
                     addDomainEntry(fonts, font, 'font');
@@ -449,6 +484,9 @@ function indexSpritesAndFonts(document, file, fileNodeId, nodes, edges, sprites,
                             override: font.override,
                             languages,
                             assetPaths,
+                            ...(colour === undefined ? {} : { colour }),
+                            ...(borderColour === undefined ? {} : { borderColour }),
+                            ...(Object.keys(textColours).length === 0 ? {} : { textColours }),
                         },
                     });
                     addEdge(edges, 'contains', fileNodeId, id, true, {}, font.location);

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';
@@ -702,10 +703,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 +771,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);

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.3';
+export const PACKAGE_VERSION = '2.8.5';
 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. 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` tint those same native glyph masks with the exact palette colour 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.
 
 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 discovers numeric and text tokens in the selected window, localisation, and scripted-GUI properties; fills meters; populates dynamic lists; chooses animated frames; varies condition-controlled visibility and enabled controls; and leaves values explicitly supplied by the caller unchanged. The same artifact gallery retains the unresolved placeholder scenario and every explicit `relatedScenarios` entry, so an agent can compare plausible data, exact authored cases, and `[dynamic_loc]` or `[X]` fallbacks in one result.
+
+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. Set `enabled` to `false` when only the supplied scenario should render, and set `preservePlaceholder` to `false` when the fallback view is not needed.
+
+```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. The retained fallback view renders 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.3",
+  "version": "2.8.5",
   "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.3/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/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.3/schemas/map-operation.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.5/schemas/map-operation.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "oneOf": [
     {

package/schemas/operation-result.schema.json

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

package/schemas/probability-analysis-result.schema.json

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

package/schemas/probability-compare-input.schema.json

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

package/schemas/probability-evaluate-input.schema.json

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

package/schemas/probability-inspect-input.schema.json

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

package/schemas/probability-render-input.schema.json

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

package/schemas/probability-scenario-set.schema.json

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

package/schemas/probability-sequence-input.schema.json

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

package/schemas/probability-simulate-input.schema.json

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

package/schemas/probability-sweep-input.schema.json

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

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
-  "version": "2.8.3",
+  "version": "2.8.5",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "2.8.3",
+      "version": "2.8.5",
       "transport": {
         "type": "stdio"
       }