hoi4-agent-tools 2.8.4 → 2.8.6

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 No unreleased changes.
 
+## 2.8.6 - 2026-08-28
+
+- Generate source-aware scripted-GUI scenarios from complete parent/child surfaces, real scripted-localisation candidates, simple threshold conditions, coherent tab states, scoped values, meter ranges, and dynamic-list rows while keeping explicit scenario values authoritative.
+- Preserve native HOI4 bitmap-font antialiasing and shadow pixels when applying face and localisation colours, including global and per-font `textcolors` palettes.
+- Prevent stale workspace artifacts and irrelevant language font atlases from blocking GUI calls, resolve alternate vanilla raster extensions and repeated path separators, and keep placeholder scenarios opt-in so their intentionally unresolved state does not pollute normal validation.
+
+## 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.

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/core/artifacts.js

@@ -131,9 +131,14 @@ export function boundedSourceHashEvidence(sourceHashes) {
     };
 }
 function assertManifestIntegrity(manifest, expected, workspace) {
+    assertManifestAddressIntegrity(manifest, expected);
     if (manifest.workspaceIdentity !== workspace.workspaceIdentity ||
-        manifest.ownerIdentity !== workspace.ownerIdentity ||
-        manifest.sha256 !== expected.sha256 ||
+        manifest.ownerIdentity !== workspace.ownerIdentity) {
+        throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact provenance manifest does not match its immutable address');
+    }
+}
+function assertManifestAddressIntegrity(manifest, expected) {
+    if (manifest.sha256 !== expected.sha256 ||
         manifest.provenanceHash !== expected.provenanceHash ||
         manifest.name !== expected.name ||
         provenanceHashFor(manifest) !== expected.provenanceHash) {
@@ -712,11 +717,11 @@ export class ArtifactStore {
                 if (child.name !== `${manifest.name}.${manifest.provenanceHash}.manifest.json`) {
                     throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact provenance manifest filename does not match its contents');
                 }
-                assertManifestIntegrity(manifest, {
+                assertManifestAddressIntegrity(manifest, {
                     sha256: path.basename(directory),
                     provenanceHash: manifest.provenanceHash,
                     name: manifest.name,
-                }, workspace);
+                });
                 const targetPath = await containedGeneratedPath(workspace.artifactRoot, path.relative(workspace.artifactRoot, path.join(directory, manifest.name)));
                 let targetBytes = 0;
                 try {
@@ -728,6 +733,8 @@ export class ArtifactStore {
                 }
                 retained.push({
                     manifest,
+                    staleIdentity: manifest.workspaceIdentity !== workspace.workspaceIdentity ||
+                        manifest.ownerIdentity !== workspace.ownerIdentity,
                     manifestPath: candidate,
                     manifestBytes: metadata.size,
                     modifiedAt: metadata.mtimeMs,
@@ -789,7 +796,8 @@ export class ArtifactStore {
             }
         };
         await reclaimDebris(await containedGeneratedPath(workspace.artifactRoot));
-        retained.sort((left, right) => left.modifiedAt - right.modifiedAt ||
+        retained.sort((left, right) => Number(right.staleIdentity) - Number(left.staleIdentity) ||
+            left.modifiedAt - right.modifiedAt ||
             compareCodeUnits(left.manifestPath, right.manifestPath));
         const current = { ...usage };
         for (const candidate of retained) {
@@ -822,7 +830,7 @@ export class ArtifactStore {
                 if (error.code !== 'ENOENT')
                     throw error;
             }
-            const verificationPrefix = `${workspace.workspaceIdentity}\0${workspace.ownerIdentity}\0${candidate.targetPath}\0`;
+            const verificationPrefix = `${candidate.manifest.workspaceIdentity}\0${candidate.manifest.ownerIdentity}\0${candidate.targetPath}\0`;
             for (const key of this.#verifiedContent.keys()) {
                 if (key.startsWith(verificationPrefix))
                     this.#verifiedContent.delete(key);

package/dist/hoi4_agent_tools/gui/assets.js

@@ -202,6 +202,7 @@ export class GuiAssetCatalog {
                 ...(definition.borderColour === undefined && base.borderColour !== undefined
                     ? { borderColour: base.borderColour }
                     : {}),
+                textColours: { ...base.textColours, ...definition.textColours },
             });
         }
     }
@@ -582,11 +583,18 @@ 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 });
+                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;
         }
@@ -739,11 +748,14 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             displayText = `${displayText} — ${displayText} — ${displayText}`;
         if (state === 'missing-localisation')
             displayText = `\u00a7R${rawText}_MISSING\u00a7!`;
-        const visibleText = visibleHoiText(displayText);
-        displayText = visibleText.text;
-        context.work.admitText(displayText, `GUI text for ${definition.name}`);
         const fontName = scalarString(property(definition.attributes, 'font', 'buttonFont'));
         const fontDefinition = fontName === undefined ? undefined : catalog.fontDefinition(fontName);
+        const visibleText = visibleHoiText(displayText, {
+            ...context.graph.textColours,
+            ...fontDefinition?.textColours,
+        });
+        displayText = visibleText.text;
+        context.work.admitText(displayText, `GUI text for ${definition.name}`);
         const resolvedFontMetrics = catalog.resolvedFontMetrics(fontName);
         const explicitFontSize = scalarNumber(property(definition.attributes, 'fontSize'), 16);
         const fontSize = explicitFontSize ??

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -62,17 +62,19 @@ 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 colourMatrix(colour) {
+function bitmapTintMarkup(id, colour, glyphs, rect) {
     const match = /^#([0-9a-f]{6})([0-9a-f]{2})?$/iu.exec(colour);
-    if (match === null)
-        return '1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0';
-    const rgb = match[1];
-    const alpha = match[2] ?? 'ff';
-    const component = (offset) => Number.parseInt(rgb.slice(offset, offset + 2), 16) / 255;
-    return `${finite(component(0))} 0 0 0 0 0 ${finite(component(2))} 0 0 0 0 0 ${finite(component(4))} 0 0 0 0 0 ${finite(Number.parseInt(alpha, 16) / 255)} 0`;
-}
-function bitmapTintDefinition(id, colour) {
-    return `<filter id="${id}" color-interpolation-filters="sRGB"><feColorMatrix type="matrix" values="${colourMatrix(colour)}"/></filter>`;
+    const rgb = match?.[1] ?? 'ffffff';
+    const alpha = match?.[2] ?? 'ff';
+    const channels = [
+        Number.parseInt(rgb.slice(0, 2), 16) / 255,
+        Number.parseInt(rgb.slice(2, 4), 16) / 255,
+        Number.parseInt(rgb.slice(4, 6), 16) / 255,
+        Number.parseInt(alpha, 16) / 255,
+    ].map(finite);
+    const [red, green, blue, opacity] = channels;
+    const matrix = `${red} 0 0 0 0 0 ${green} 0 0 0 0 0 ${blue} 0 0 0 0 0 ${opacity} 0`;
+    return `<defs><filter id="${id}" filterUnits="userSpaceOnUse" ${rectAttributes(rect)} color-interpolation-filters="sRGB"><feColorMatrix type="matrix" values="${matrix}"/></filter></defs><g filter="url(#${id})">${glyphs}</g>`;
 }
 function actualGlyphMarkup(glyphLine, originX, baseline, horizontalScale) {
     if (glyphLine.source === 'fontkit-path')
@@ -138,9 +140,14 @@ function renderText(element, toolText) {
                 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 filterId = `gui-font-tint-${sha256Bytes(key).slice(0, 20)}`;
-                    definitions.push(bitmapTintDefinition(filterId, run.colour));
-                    return `<g clip-path="url(#${clipId})" filter="url(#${filterId})" data-font-colour="${run.colour}">${glyphs}</g>`;
+                    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>`;
             });
@@ -166,8 +173,9 @@ function renderText(element, toolText) {
             const glyphs = actualGlyphMarkup(glyphLine, originX, baseline, horizontalScale);
             if (text.colour === undefined)
                 return `<g data-font-sha256="${glyphLine.sourceHash}">${glyphs}${inlineIconMarkup}</g>`;
-            const filterId = `gui-font-tint-${sha256Bytes(`${element.id}:${index}:${text.colour}`).slice(0, 20)}`;
-            return `<g data-font-sha256="${glyphLine.sourceHash}" data-font-colour="${text.colour}"><defs>${bitmapTintDefinition(filterId, text.colour)}</defs><g filter="url(#${filterId})">${glyphs}</g>${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, {