hoi4-agent-tools 2.3.13 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.5.0 - 2026-08-09
+
+- Added exact continuous-focus coordinates and linked palette IDs to compact national focus inspection results.
+- Added source-first probability inspection that discovers compatible adapters, candidate counts, and selector examples without requiring the caller to guess a surface type.
+- Changed empty or mismatched probability inspection into an actionable discovery result with a reason and suggested adapter while keeping evaluation, sweeps, and simulation strict.
+- Prevented focus-tree blocks from being misclassified as decision or mission weighted surfaces.
+
+## 2.4.0 - 2026-08-09
+
+- Added named value-driven scripted-GUI scenario matrices with deterministic SVG, PNG, JSON, and per-element visibility, movement, size, text, and frame-change evidence.
+- Added scenario assertions for visible and hidden elements, background or panel containment, and exact label-to-control centering, with source-linked diagnostics across every supplied variant.
+- Modelled native HOI4 button-text centering and added automatic diagnostics for visibly off-center labels and text or controls crossing a parent background boundary.
+- Updated the production MCP SDK to 1.30.0, the official Inspector to 2.1.0, the Registry publisher to 1.8.1, and patched dependencies; the dependency audit reports no known vulnerabilities.
+- Updated the Inspector harness for the current CLI entry point, result envelope, explicit environment forwarding, and longer connection startup budget.
+- Generalized installed-game integration tests so mods without their own focus, event, or technology definitions still qualify and use the available vanilla-backed analysis surfaces.
+
 ## 2.3.13 - 2026-08-06
 
 - Repacked sparse sibling fan-outs around their structural parent instead of preserving avoidable long prerequisite connectors.

package/README.md

@@ -5,7 +5,7 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 ## What it does
 
 - Focus trees: inspect structure and references, render layouts, create trees, and reorganize existing branches.
-- Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render states; create or repair interface source.
+- Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render value-driven variants, states, resolutions, hierarchy, and click regions; diagnose alignment, visibility, clipping, panel containment, and button-label centering; create or repair interface source.
 - Maps: inspect provinces, states, regions, adjacency, supply, and railways; render layers; create and repair exact map data.
 - Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
 - Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
@@ -13,7 +13,7 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 
 ## Setup
 
-Requires Node.js 22 or 24.
+Requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
 
 ```bash
 npm install --global hoi4-agent-tools@latest
@@ -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 and report 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 states and resolutions offline.                                              |
-| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                  |
-| `hoi4.map_inspect`          | Read map, state, province, region, supply, and railway data.                            |
-| `hoi4.map_render`           | Render map layers and overlays.                                                         |
-| `hoi4.map_rewrite`          | Create or update map data from an ordered list of exact changes.                        |
-| `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, candidates, required inputs, and supported analysis.             |
-| `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 GUI scenario variants, states, resolutions, hierarchy, and layout diagnostics.    |
+| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                   |
+| `hoi4.map_inspect`          | Read map, state, province, region, supply, and railway data.                             |
+| `hoi4.map_render`           | Render map layers and overlays.                                                          |
+| `hoi4.map_rewrite`          | Create or update map data from an ordered list of exact changes.                         |
+| `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>`.
 
@@ -70,7 +70,7 @@ Connecting and listing tools does not scan mod source. Compact tool schemas and
 Ask your agent in normal task language. A typical workflow is inspect, render, rewrite, then inspect the result. The agent can call a raster tool when a pixel review is useful without paying that cost during every structural operation.
 
 - Focus trees: "Create a complete national focus tree for this route specification," or "Compact this existing tree into a balanced, readable layout." Existing trees can use a plan-free compact reflow; new trees use a complete plan. See [Focus trees](docs/focus.md).
-- Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render this window at common resolutions and fix clipping, missing assets, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
+- Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render every value-driven version of this window and fix hidden controls, off-center button text, background alignment, clipping, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
 - Maps: "Create a state from these exact provinces," or "Inspect this state and split these provinces while keeping supply and railway references valid." See [Maps](docs/map.md).
 - Event chains: "Trace every route from this event and explain where its flags and variables change," or "Compare the workspace event graph with its previous revision and render the affected routes." See [Event chains](docs/events.md).
 - Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).

package/dist/hoi4_agent_tools/gui/layout.js

@@ -384,18 +384,23 @@ function frameFor(element, sprite, scenario) {
                 : 0;
     return Math.min(frameCount - 1, mapped);
 }
-function alignment(attributes) {
-    const format = scalarString(property(attributes, 'format'))?.toLowerCase() ?? '';
+function alignment(attributes, buttonText) {
+    const explicitFormat = scalarString(property(attributes, 'format'))?.toLowerCase();
+    const format = explicitFormat ?? '';
     const horizontalAlignment = format.includes('center')
         ? 'center'
         : format.includes('right')
             ? 'right'
-            : 'left';
+            : buttonText && explicitFormat === undefined
+                ? 'center'
+                : 'left';
     const verticalAlignment = format.includes('bottom')
         ? 'bottom'
         : format.includes('center')
             ? 'center'
-            : 'top';
+            : buttonText && explicitFormat === undefined
+                ? 'center'
+                : 'top';
     return { horizontalAlignment, verticalAlignment };
 }
 class GuiSceneWorkBudget {
@@ -523,7 +528,8 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             }
         }
     }
-    const rawText = scalarString(property(definition.attributes, 'text', 'buttonText'));
+    const rawButtonText = scalarString(property(definition.attributes, 'buttonText'));
+    const rawText = scalarString(property(definition.attributes, 'text')) ?? rawButtonText;
     let text;
     if (rawText !== undefined) {
         const resolved = resolveTokenText(rawText, scenario, context.localisation, rowValues);
@@ -568,7 +574,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             measuredWidth,
             measuredHeight,
             metricSource: wrapped.metricSource,
-            ...alignment(definition.attributes),
+            ...alignment(definition.attributes, rawButtonText !== undefined),
             ...(fontName === undefined ? {} : { fontName }),
             glyphLines,
             overflowX: width > 0 && measuredWidth > width + 0.01,

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -4,6 +4,7 @@ import { ServiceError } from '../core/result.js';
 import { GUI_SCENARIO_MAX_KEYS, GUI_SCENARIO_MAX_LIST_KEYS, GUI_SCENARIO_MAX_ROWS, GUI_SCENARIO_MAX_STRING_CHARACTERS, } from './limits.js';
 const scalarSchema = z.union([z.string().max(16_384), z.number(), z.boolean()]);
 const objectSchema = z.record(z.string(), scalarSchema);
+const elementNameSchema = z.string().min(1).max(256);
 const previewStateSchema = z.enum([
     'normal',
     'hover',
@@ -124,6 +125,15 @@ const GuiPreviewScenarioBodySchema = z
     scrollOffsets: z.record(z.string(), z.number().min(0)).default({}),
     guiCosts: z.record(z.string(), z.number()).default({}),
     scriptCosts: z.record(z.string(), z.number()).default({}),
+    expectations: z
+        .object({
+        visible: z.array(elementNameSchema).max(10_000).default([]),
+        hidden: z.array(elementNameSchema).max(10_000).default([]),
+        containedBy: z.record(elementNameSchema, elementNameSchema).default({}),
+        centeredOn: z.record(elementNameSchema, elementNameSchema).default({}),
+    })
+        .strict()
+        .default({ visible: [], hidden: [], containedBy: {}, centeredOn: {} }),
 })
     .strict()
     .superRefine((scenario, context) => {

package/dist/hoi4_agent_tools/gui/studio.js

@@ -325,6 +325,72 @@ function safeSlug(value) {
 function scenarioWith(base, patch) {
     return parsePreviewScenario({ ...base, ...patch });
 }
+function assertUniqueScenarioIds(scenarios) {
+    const seen = new Set();
+    for (const scenario of scenarios) {
+        if (seen.has(scenario.id)) {
+            throw new ServiceError('GUI_SCENARIO_ID_DUPLICATE', `GUI scenario id must be unique within one request: ${scenario.id}`, { scenarioId: scenario.id });
+        }
+        seen.add(scenario.id);
+    }
+}
+function scenarioMatrixEvidence(scenes) {
+    const primary = scenes[0];
+    if (primary === undefined)
+        return { offline: true, scenarios: [], changes: [] };
+    const elementKey = (element) => `${element.sourceId}#${element.rowIndex ?? 0}`;
+    const primaryByKey = new Map(primary.elements.map((element) => [elementKey(element), element]));
+    return {
+        offline: true,
+        scenarios: scenes.map((scene) => ({
+            scenario: scene.scenario,
+            sourceRevision: scene.sourceRevision,
+            fidelity: scene.fidelity,
+            visibleElements: scene.elements
+                .filter(({ visible }) => visible)
+                .map(({ id, name }) => ({ id, name })),
+        })),
+        changes: scenes.slice(1).map((scene) => {
+            const currentByKey = new Map(scene.elements.map((element) => [elementKey(element), element]));
+            const keys = [...new Set([...primaryByKey.keys(), ...currentByKey.keys()])].sort((left, right) => compareCodeUnits(left, right));
+            const shown = [];
+            const hidden = [];
+            const moved = [];
+            const resized = [];
+            const textChanged = [];
+            const frameChanged = [];
+            for (const key of keys) {
+                const before = primaryByKey.get(key);
+                const after = currentByKey.get(key);
+                if (before?.visible !== true && after?.visible === true)
+                    shown.push(after.name);
+                if (before?.visible === true && after?.visible !== true)
+                    hidden.push(before.name);
+                if (before === undefined || after === undefined)
+                    continue;
+                if (before.unclippedRect.x !== after.unclippedRect.x ||
+                    before.unclippedRect.y !== after.unclippedRect.y)
+                    moved.push(after.name);
+                if (before.unclippedRect.width !== after.unclippedRect.width ||
+                    before.unclippedRect.height !== after.unclippedRect.height)
+                    resized.push(after.name);
+                if (before.text?.text !== after.text?.text)
+                    textChanged.push(after.name);
+                if (before.sprite?.frame !== after.sprite?.frame)
+                    frameChanged.push(after.name);
+            }
+            return {
+                scenarioId: scene.scenario.id,
+                shown,
+                hidden,
+                moved,
+                resized,
+                textChanged,
+                frameChanged,
+            };
+        }),
+    };
+}
 function fullImage(render) {
     const image = render.images.find(({ variant }) => variant === 'full') ?? render.images[0];
     if (image === undefined)
@@ -460,6 +526,7 @@ export class ScriptedGuiStudio {
         input.signal?.throwIfAborted();
         const scenario = parsePreviewScenario(input.scenario);
         const relatedScenarios = (input.relatedScenarios ?? []).map(parsePreviewScenario);
+        assertUniqueScenarioIds([scenario, ...relatedScenarios]);
         const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [scenario.language, ...relatedScenarios.map(({ language }) => language)]);
         const budget = new RenderBudget();
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget);
@@ -510,11 +577,37 @@ export class ScriptedGuiStudio {
         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 scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [scenario.language, baselineScenario.language]);
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [
+            scenario.language,
+            baselineScenario.language,
+            ...relatedScenarios.map(({ language }) => language),
+        ]);
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget);
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
         const render = await renderGuiScene(scene, undefined, input.signal, budget);
+        const scenarioScenes = [scene];
+        const scenarioItems = [];
+        for (const variantScenario of [scenario, ...relatedScenarios]) {
+            input.signal?.throwIfAborted();
+            const variantScene = variantScenario.id === scenario.id
+                ? scene
+                : await buildGuiScene(scanned.graph, scanned.files, input.windowName, variantScenario, catalog);
+            if (variantScene !== scene)
+                scenarioScenes.push(variantScene);
+            const variantRender = variantScene === scene
+                ? render
+                : await renderGuiScene(variantScene, ['full'], input.signal, new RenderBudget());
+            const image = fullImage(variantRender);
+            scenarioItems.push({
+                label: variantScenario.description ?? variantScenario.id,
+                png: image.png,
+                width: image.width,
+                height: image.height,
+            });
+        }
         const stateScenes = [];
         const stateItems = [];
         for (const state of input.states ?? [...galleryStates]) {
@@ -556,21 +649,29 @@ export class ScriptedGuiStudio {
         const baselineScene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, baselineScenario, catalog);
         const baselineRender = await renderGuiScene(baselineScene, ['full'], input.signal, budget);
         const comparison = await compareGuiImages(fullImage(baselineRender).png, fullImage(render).png, budget, input.signal);
-        const validation = await validateGuiScene(scanned.graph, scene, scanned.files, resolutionScenes, catalog);
+        const validation = await validateGuiScene(scanned.graph, scene, scanned.files, scenarioScenes.slice(1), catalog);
         const stateValidation = validateStateMatrix(stateScenes);
         const resolutionValidation = validateResolutionDrift(resolutionScenes);
         validation.diagnostics.push(...stateValidation.diagnostics, ...resolutionValidation.diagnostics);
         validation.checks.push(...stateValidation.checks, ...resolutionValidation.checks);
         const completeValidation = withGraphDiagnostics(scanned.graph, validation);
+        const scenarioGallerySvg = renderGallerySvg(`${input.windowName} scripted scenario matrix`, scenarioItems);
         const stateGallerySvg = renderGallerySvg(`${input.windowName} state matrix`, stateItems);
         const resolutionGallerySvg = renderGallerySvg(`${input.windowName} resolution and UI-scale matrix`, resolutionItems);
+        const scenarioGallerySize = galleryDimensions(scenarioItems);
         const stateGallerySize = galleryDimensions(stateItems);
         const resolutionGallerySize = galleryDimensions(resolutionItems);
-        budget.reserve(stateGallerySize.width, stateGallerySize.height, 'GUI state gallery PNG');
-        budget.reserve(resolutionGallerySize.width, resolutionGallerySize.height, 'GUI resolution gallery PNG');
-        budget.reserveRasterOperation(`gui-gallery:${sha256Bytes(stateGallerySvg)}`, 'GUI state gallery SVG rasterization');
-        budget.reserveRasterOperation(`gui-gallery:${sha256Bytes(resolutionGallerySvg)}`, 'GUI resolution gallery SVG rasterization');
-        const [stateGalleryPng, resolutionGalleryPng] = await Promise.all([
+        const galleryBudget = new RenderBudget();
+        galleryBudget.reserve(scenarioGallerySize.width, scenarioGallerySize.height, 'GUI scripted scenario gallery PNG');
+        galleryBudget.reserve(stateGallerySize.width, stateGallerySize.height, 'GUI state gallery PNG');
+        galleryBudget.reserve(resolutionGallerySize.width, resolutionGallerySize.height, 'GUI resolution gallery PNG');
+        galleryBudget.reserveRasterOperation(`gui-gallery:${sha256Bytes(scenarioGallerySvg)}`, 'GUI scripted scenario gallery SVG rasterization');
+        galleryBudget.reserveRasterOperation(`gui-gallery:${sha256Bytes(stateGallerySvg)}`, 'GUI state gallery SVG rasterization');
+        galleryBudget.reserveRasterOperation(`gui-gallery:${sha256Bytes(resolutionGallerySvg)}`, 'GUI resolution gallery SVG rasterization');
+        const [scenarioGalleryPng, stateGalleryPng, resolutionGalleryPng] = await Promise.all([
+            sharp(Buffer.from(scenarioGallerySvg), { limitInputPixels: RENDER_MAX_PIXELS })
+                .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+                .toBuffer(),
             sharp(Buffer.from(stateGallerySvg), { limitInputPixels: RENDER_MAX_PIXELS })
                 .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
                 .toBuffer(),
@@ -598,7 +699,10 @@ export class ScriptedGuiStudio {
         add(`${slug}-scenario.json`, 'application/json', render.scenarioJson, 'gui-preview-scenario');
         add(`${slug}-fidelity.json`, 'application/json', `${canonicalJson({ offline: true, fidelity: render.fidelity })}\n`, 'gui-fidelity-report');
         add(`${slug}-source-graph.json`, 'application/json', `${canonicalJson(scanned.graph)}\n`, 'gui-source-graph');
-        add(`${slug}-validation.json`, 'application/json', `${canonicalJson(completeValidation)}\n`, 'gui-validation-report', [scene, ...stateScenes, ...resolutionScenes]);
+        add(`${slug}-validation.json`, 'application/json', `${canonicalJson(completeValidation)}\n`, 'gui-validation-report', [...scenarioScenes, ...stateScenes, ...resolutionScenes]);
+        add(`${slug}-scenario-matrix.svg`, 'image/svg+xml', scenarioGallerySvg, 'gui-scripted-scenario-matrix', scenarioScenes);
+        add(`${slug}-scenario-matrix.png`, 'image/png', scenarioGalleryPng, 'gui-scripted-scenario-matrix', scenarioScenes);
+        add(`${slug}-scenario-matrix.json`, 'application/json', `${canonicalJson(scenarioMatrixEvidence(scenarioScenes))}\n`, 'gui-scripted-scenario-matrix-json', scenarioScenes);
         add(`${slug}-state-matrix.svg`, 'image/svg+xml', stateGallerySvg, 'gui-state-matrix', stateScenes);
         add(`${slug}-state-matrix.png`, 'image/png', stateGalleryPng, 'gui-state-matrix', stateScenes);
         add(`${slug}-state-matrix.json`, 'application/json', `${canonicalJson({ offline: true, scenarios: stateScenes.map(({ scenario: stateScenario, fidelity }) => ({ scenario: stateScenario, fidelity })) })}\n`, 'gui-state-matrix-json', stateScenes);
@@ -615,6 +719,7 @@ export class ScriptedGuiStudio {
             artifacts: stored,
             filesScanned: scanned.graph.filesScanned,
             render,
+            scenarioScenes,
             stateScenes,
             resolutionScenes,
             comparison,

package/dist/hoi4_agent_tools/gui/validators.js

@@ -96,6 +96,177 @@ function contains(outer, inner, tolerance = 0.01) {
         inner.x + inner.width <= outer.x + outer.width + tolerance &&
         inner.y + inner.height <= outer.y + outer.height + tolerance);
 }
+function visualTextBounds(element) {
+    const text = element.text;
+    if (text === undefined)
+        return element.unclippedRect;
+    const width = Math.min(element.unclippedRect.width, text.measuredWidth);
+    const height = Math.min(element.unclippedRect.height, text.measuredHeight);
+    const x = text.horizontalAlignment === 'center'
+        ? element.unclippedRect.x + (element.unclippedRect.width - width) / 2
+        : text.horizontalAlignment === 'right'
+            ? element.unclippedRect.x + element.unclippedRect.width - width
+            : element.unclippedRect.x;
+    const y = text.verticalAlignment === 'center'
+        ? element.unclippedRect.y + (element.unclippedRect.height - height) / 2
+        : text.verticalAlignment === 'bottom'
+            ? element.unclippedRect.y + element.unclippedRect.height - height
+            : element.unclippedRect.y;
+    return { x, y, width, height };
+}
+function centreDelta(inner, outer) {
+    return {
+        x: inner.x + inner.width / 2 - (outer.x + outer.width / 2),
+        y: inner.y + inner.height / 2 - (outer.y + outer.height / 2),
+    };
+}
+function elementMatches(element, selector) {
+    return element.name === selector || element.id === selector || element.sourceId === selector;
+}
+function expectedElements(scene, selector) {
+    return scene.elements.filter((element) => elementMatches(element, selector));
+}
+function validateScenarioExpectations(scene, diagnostics) {
+    const { expectations } = scene.scenario;
+    const missing = new Set();
+    const requireElements = (selector) => {
+        const matches = expectedElements(scene, selector);
+        if (matches.length === 0 && !missing.has(selector)) {
+            missing.add(selector);
+            diagnostics.push({
+                code: 'GUI_EXPECTED_ELEMENT_MISSING',
+                severity: 'error',
+                category: 'design',
+                message: `Scenario ${scene.scenario.id} expects GUI element ${selector}, but the window does not contain it.`,
+                details: { scenarioId: scene.scenario.id, element: selector },
+            });
+        }
+        return matches;
+    };
+    for (const selector of expectations.visible) {
+        const matches = requireElements(selector);
+        if (matches.length > 0 && !matches.some(({ visible }) => visible))
+            diagnostics.push({
+                code: 'GUI_EXPECTED_ELEMENT_HIDDEN',
+                severity: 'error',
+                category: 'design',
+                message: `Scenario ${scene.scenario.id} expects ${selector} to be visible, but every matching element is hidden.`,
+                details: { scenarioId: scene.scenario.id, element: selector },
+            });
+    }
+    for (const selector of expectations.hidden) {
+        const matches = requireElements(selector);
+        if (matches.some(({ visible }) => visible))
+            diagnostics.push({
+                code: 'GUI_EXPECTED_ELEMENT_VISIBLE',
+                severity: 'error',
+                category: 'design',
+                message: `Scenario ${scene.scenario.id} expects ${selector} to be hidden, but a matching element is visible.`,
+                details: { scenarioId: scene.scenario.id, element: selector },
+            });
+    }
+    for (const [selector, ownerSelector] of Object.entries(expectations.containedBy)) {
+        const elements = requireElements(selector).filter(({ visible }) => visible);
+        const owners = requireElements(ownerSelector).filter(({ visible }) => visible);
+        for (const element of elements) {
+            if (owners.some((owner) => contains(owner.unclippedRect, element.unclippedRect, 0.5)))
+                continue;
+            diagnostics.push(issue('GUI_CONTENT_OUTSIDE_EXPECTED_BACKGROUND', 'error', 'layout', `Scenario ${scene.scenario.id} places ${selector} outside its expected background or panel ${ownerSelector}.`, element, {
+                scenarioId: scene.scenario.id,
+                element: selector,
+                expectedContainer: ownerSelector,
+            }));
+        }
+    }
+    for (const [selector, ownerSelector] of Object.entries(expectations.centeredOn)) {
+        const elements = requireElements(selector).filter(({ visible }) => visible);
+        const owners = requireElements(ownerSelector).filter(({ visible }) => visible);
+        for (const element of elements) {
+            const target = owners
+                .filter((owner) => intersection(owner.unclippedRect, element.unclippedRect) !== undefined)
+                .toSorted((left, right) => area(left.unclippedRect) - area(right.unclippedRect))[0];
+            if (target === undefined) {
+                diagnostics.push(issue('GUI_EXPECTED_CENTER_TARGET_MISSING', 'error', 'layout', `Scenario ${scene.scenario.id} cannot center ${selector} because it does not overlap visible target ${ownerSelector}.`, element, { scenarioId: scene.scenario.id, element: selector, target: ownerSelector }));
+                continue;
+            }
+            const delta = centreDelta(visualTextBounds(element), target.unclippedRect);
+            const toleranceX = Math.max(2, target.unclippedRect.width * 0.025);
+            const toleranceY = Math.max(2, target.unclippedRect.height * 0.08);
+            if (Math.abs(delta.x) <= toleranceX && Math.abs(delta.y) <= toleranceY)
+                continue;
+            diagnostics.push(issue('GUI_EXPECTED_CENTERING_MISMATCH', 'error', 'layout', `Scenario ${scene.scenario.id} offsets ${selector} from the center of ${ownerSelector} by ${delta.x.toFixed(2)}px horizontally and ${delta.y.toFixed(2)}px vertically.`, element, {
+                scenarioId: scene.scenario.id,
+                element: selector,
+                target: ownerSelector,
+                deltaX: delta.x,
+                deltaY: delta.y,
+            }));
+        }
+    }
+}
+function validateButtonLabelsAndBackgrounds(scene, diagnostics) {
+    const visible = scene.elements.filter((element) => element.visible);
+    const byId = new Map(scene.elements.map((element) => [element.id, element]));
+    const buttons = visible.filter((element) => element.clickable && /button/iu.test(element.elementType));
+    const labels = visible.filter((element) => element.text !== undefined);
+    const inferredButtonByLabel = new Map();
+    const inferredLabelCountByButton = new Map();
+    for (const label of labels) {
+        if (buttons.some(({ id }) => id === label.id))
+            continue;
+        const parentButton = label.parentId === undefined ? undefined : buttons.find(({ id }) => id === label.parentId);
+        const overlayButton = buttons
+            .filter((button) => {
+            if (button.zIndex > label.zIndex || button.id === label.id)
+                return false;
+            const overlap = intersection(button.unclippedRect, label.unclippedRect);
+            return (overlap !== undefined && area(overlap) / Math.max(1, area(label.unclippedRect)) >= 0.6);
+        })
+            .toSorted((left, right) => area(left.unclippedRect) - area(right.unclippedRect))[0];
+        const inferredButton = parentButton ?? overlayButton;
+        if (inferredButton === undefined)
+            continue;
+        inferredButtonByLabel.set(label.id, inferredButton);
+        inferredLabelCountByButton.set(inferredButton.id, (inferredLabelCountByButton.get(inferredButton.id) ?? 0) + 1);
+    }
+    for (const label of labels) {
+        const ownButton = buttons.find(({ id }) => id === label.id);
+        const inferredButton = inferredButtonByLabel.get(label.id);
+        const button = ownButton ??
+            (inferredButton !== undefined && inferredLabelCountByButton.get(inferredButton.id) === 1
+                ? inferredButton
+                : undefined);
+        if (button !== undefined) {
+            const delta = centreDelta(visualTextBounds(label), button.unclippedRect);
+            const toleranceX = Math.max(2, button.unclippedRect.width * 0.025);
+            const toleranceY = Math.max(2, button.unclippedRect.height * 0.08);
+            if (Math.abs(delta.x) > toleranceX || Math.abs(delta.y) > toleranceY)
+                diagnostics.push(issue('GUI_BUTTON_LABEL_OFF_CENTER', 'warning', 'layout', `${label.name} is offset from button ${button.name} by ${delta.x.toFixed(2)}px horizontally and ${delta.y.toFixed(2)}px vertically in scenario ${scene.scenario.id}.`, label, {
+                    scenarioId: scene.scenario.id,
+                    label: label.name,
+                    button: button.name,
+                    deltaX: delta.x,
+                    deltaY: delta.y,
+                }));
+        }
+        let parent = label.parentId === undefined ? undefined : byId.get(label.parentId);
+        while (parent !== undefined && parent.sprite === undefined)
+            parent = parent.parentId === undefined ? undefined : byId.get(parent.parentId);
+        if (parent !== undefined &&
+            !contains(parent.unclippedRect, label.unclippedRect, 0.5) &&
+            intersection(parent.unclippedRect, label.unclippedRect) !== undefined)
+            diagnostics.push(issue('GUI_CONTENT_CROSSES_BACKGROUND_EDGE', 'warning', 'layout', `${label.name} crosses the visible background boundary of ${parent.name} in scenario ${scene.scenario.id}.`, label, { scenarioId: scene.scenario.id, element: label.name, background: parent.name }));
+    }
+    for (const control of visible.filter((element) => element.clickable && element.text === undefined)) {
+        let parent = control.parentId === undefined ? undefined : byId.get(control.parentId);
+        while (parent !== undefined && parent.sprite === undefined)
+            parent = parent.parentId === undefined ? undefined : byId.get(parent.parentId);
+        if (parent !== undefined &&
+            !contains(parent.unclippedRect, control.unclippedRect, 0.5) &&
+            intersection(parent.unclippedRect, control.unclippedRect) !== undefined)
+            diagnostics.push(issue('GUI_CONTENT_CROSSES_BACKGROUND_EDGE', 'warning', 'layout', `${control.name} crosses the visible background boundary of ${parent.name} in scenario ${scene.scenario.id}.`, control, { scenarioId: scene.scenario.id, element: control.name, background: parent.name }));
+    }
+}
 function sameRect(left, right) {
     return (Math.abs(left.x - right.x) < 0.01 &&
         Math.abs(left.y - right.y) < 0.01 &&
@@ -900,19 +1071,27 @@ export async function validateGuiScene(graph, scene, files, relatedScenes = [],
         };
     }
     const diagnostics = validationCollector();
-    const work = new GuiValidationWorkBudget();
-    diagnostics.pushMany(scene.diagnostics);
-    validateOverlapAndGeometry(scene, diagnostics, work);
-    validateAlignmentAndSpacing(scene, diagnostics, work);
-    validateReferencesAndScript(graph, scene, diagnostics);
-    validateScrollAndTabs(scene, diagnostics);
+    for (const currentScene of [scene, ...relatedScenes]) {
+        const sceneDiagnostics = validationCollector();
+        const work = new GuiValidationWorkBudget();
+        sceneDiagnostics.pushMany(currentScene.diagnostics);
+        validateOverlapAndGeometry(currentScene, sceneDiagnostics, work);
+        validateAlignmentAndSpacing(currentScene, sceneDiagnostics, work);
+        validateButtonLabelsAndBackgrounds(currentScene, sceneDiagnostics);
+        validateScenarioExpectations(currentScene, sceneDiagnostics);
+        validateReferencesAndScript(graph, currentScene, sceneDiagnostics);
+        validateScrollAndTabs(currentScene, sceneDiagnostics);
+        diagnostics.pushMany(sceneDiagnostics.values().map((diagnostic) => ({
+            ...diagnostic,
+            details: { ...diagnostic.details, scenarioId: currentScene.scenario.id },
+        })));
+    }
     const selectedSpriteNames = new Set();
-    for (const element of scene.elements)
-        if (element.sprite !== undefined)
-            selectedSpriteNames.add(element.sprite.spriteName);
+    for (const currentScene of [scene, ...relatedScenes])
+        for (const element of currentScene.elements)
+            if (element.sprite !== undefined)
+                selectedSpriteNames.add(element.sprite.spriteName);
     await validateGuiAnimationsInto(graph, files, selectedSpriteNames, catalog, diagnostics);
-    if (relatedScenes.length > 0)
-        validateResolutionDriftInto([scene, ...relatedScenes], diagnostics);
     return validationResult(diagnostics.values(), [
         'GUI_VALIDATION_DIAGNOSTICS_TRUNCATED',
         'GUI_VALIDATION_COMPARISON_BUDGET_BLOCKED',
@@ -922,6 +1101,14 @@ export async function validateGuiScene(graph, scene, files, relatedScenes = [],
         'GUI_TEXT_OVERFLOW',
         'GUI_INCONSISTENT_ALIGNMENT',
         'GUI_INCONSISTENT_SPACING',
+        'GUI_BUTTON_LABEL_OFF_CENTER',
+        'GUI_CONTENT_CROSSES_BACKGROUND_EDGE',
+        'GUI_EXPECTED_ELEMENT_MISSING',
+        'GUI_EXPECTED_ELEMENT_HIDDEN',
+        'GUI_EXPECTED_ELEMENT_VISIBLE',
+        'GUI_CONTENT_OUTSIDE_EXPECTED_BACKGROUND',
+        'GUI_EXPECTED_CENTER_TARGET_MISSING',
+        'GUI_EXPECTED_CENTERING_MISMATCH',
         'GUI_INVALID_SIZE',
         'GUI_CHILD_OUTSIDE_CLIPPED_PARENT',
         'GUI_CLICK_BOUNDS_MISMATCH',

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

@@ -31,6 +31,11 @@ const focusInspectOutputSchema = strictOperationResultSchema(z
         branchCount: nonNegativeIntegerSchema,
         continuousPaletteCount: nonNegativeIntegerSchema,
         continuousFocusCount: nonNegativeIntegerSchema,
+        continuousFocusPosition: z
+            .object({ x: z.number().int(), y: z.number().int() })
+            .strict()
+            .nullable(),
+        continuousFocusPaletteIds: z.array(z.string().max(256)).max(100),
         resolvedTitleCount: nonNegativeIntegerSchema,
         layoutHash: sha256Schema,
         layoutDecisionCount: nonNegativeIntegerSchema,
@@ -601,7 +606,7 @@ export function registerFocusTools(server, engine, context) {
     const workbench = new FocusWorkbench(engine.resolver, engine.transactions, engine.artifacts);
     server.registerTool('hoi4.focus_inspect', {
         title: 'Inspect focus trees',
-        description: 'Inspect national trees or continuous palettes for creation and cleanup, including complete plans, references, diagnostics, and stable layout decisions.',
+        description: 'Inspect national trees or continuous palettes for creation and cleanup, including continuous-focus placement, complete plans, references, diagnostics, and stable layout decisions.',
         inputSchema: focusInspectInput,
         outputSchema: focusInspectOutputSchema,
         annotations: artifactProducing,
@@ -791,6 +796,8 @@ export function registerFocusTools(server, engine, context) {
                     branchCount: plan.branchGroups.length,
                     continuousPaletteCount: plan.continuousFocusPaletteIds.length,
                     continuousFocusCount: plan.continuousFocusIds.length,
+                    continuousFocusPosition: plan.continuousFocusPosition ?? null,
+                    continuousFocusPaletteIds: plan.continuousFocusPaletteIds.slice(0, 100),
                     resolvedTitleCount: plan.focuses.filter(({ id }) => presentation.entries[id]?.titleSourceLocation !== undefined).length,
                     layoutHash: layout.layoutHash,
                     layoutDecisionCount: layout.decisions.length,