hoi4-agent-tools 2.8.0 → 2.8.2

package/dist/hoi4_agent_tools/gui/studio.js

@@ -2,7 +2,7 @@ import sharp from 'sharp';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { ArtifactStore, boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
-import { compareCodeUnits, canonicalJson, deterministicId, sha256Bytes, } from '../core/canonical.js';
+import { compareCodeUnits, canonicalJson, deterministicId, hashCanonical, sha256Bytes, } from '../core/canonical.js';
 import { DiagnosticCollector } from '../core/diagnostic-collector.js';
 import { sortDiagnostics } from '../core/diagnostics.js';
 import { CoreEngine } from '../core/engine.js';
@@ -15,6 +15,7 @@ import { TRANSACTION_MAX_DIAGNOSTICS } from '../core/transaction-limits.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { isSafeAnimationSourcePath } from './animation-manifest.js';
 import { GuiAssetCatalog, parseBmFont } from './assets.js';
+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';
@@ -174,6 +175,20 @@ function guiDefinitionPatterns(workspace) {
         ]),
     ].sort((left, right) => compareCodeUnits(left, right));
 }
+function guiLayoutPatterns(workspace) {
+    return [...new Set(under(workspace.registration.roots.interface, ['**/*.gui']))].sort((left, right) => compareCodeUnits(left, right));
+}
+function guiLinkedDefinitionPatterns(workspace) {
+    const roots = workspace.registration.roots;
+    return [
+        ...new Set([
+            ...under(roots.interface, ['**/*.gfx']),
+            ...under(roots.gfx, ['**/*.gfx']),
+            ...under(roots.scriptedGui, ['**/*.txt']),
+            ...staticGuiDefinitionPatterns,
+        ]),
+    ].sort((left, right) => compareCodeUnits(left, right));
+}
 function guiLocalisationPatterns(workspace, languages = ['l_english']) {
     const roots = workspace.registration.roots;
     const languageDirectories = [...new Set(languages)].map((language) => {
@@ -206,9 +221,17 @@ function referenceVariants(value) {
     if (normalized === undefined)
         return [];
     const extension = path.posix.extname(normalized);
+    const rasterExtensions = ['.png', '.bmp', '.tga', '.dds', '.svg'];
     const candidates = extension.length === 0
-        ? ['.fnt', '.ttf', '.otf', '.woff', '.woff2', '.png', '.bmp', '.tga', '.dds', '.svg'].map((suffix) => `${normalized}${suffix}`)
-        : [normalized];
+        ? ['.fnt', '.ttf', '.otf', '.woff', '.woff2', ...rasterExtensions].map((suffix) => `${normalized}${suffix}`)
+        : rasterExtensions.includes(extension.toLowerCase())
+            ? [
+                normalized,
+                ...rasterExtensions
+                    .filter((candidate) => candidate !== extension.toLowerCase())
+                    .map((candidate) => `${normalized.slice(0, -extension.length)}${candidate}`),
+            ]
+            : [normalized];
     return candidates;
 }
 function basenameFallbackPatterns(exactPaths, exactFiles) {
@@ -223,7 +246,35 @@ function basenameFallbackPatterns(exactPaths, exactFiles) {
 }
 function selectedElements(graph, windowName) {
     const byId = new Map(graph.elements.map((element) => [element.id, element]));
-    const pending = graph.elements.filter(({ name }) => name === windowName).map(({ id }) => id);
+    const relatedScriptedGuiNames = new Set(graph.scriptedGuis
+        .filter((definition) => definition.windowName === windowName || definition.parentWindowName === windowName)
+        .map(({ name }) => name));
+    let addedRelatedScriptedGui = true;
+    while (addedRelatedScriptedGui) {
+        addedRelatedScriptedGui = false;
+        for (const definition of graph.scriptedGuis) {
+            if (definition.parentScriptedGui === undefined ||
+                !relatedScriptedGuiNames.has(definition.parentScriptedGui) ||
+                relatedScriptedGuiNames.has(definition.name))
+                continue;
+            relatedScriptedGuiNames.add(definition.name);
+            addedRelatedScriptedGui = true;
+        }
+    }
+    const selectedRootNames = new Set([windowName]);
+    for (const scripted of graph.scriptedGuis.filter(({ name }) => relatedScriptedGuiNames.has(name))) {
+        if (scripted.windowName !== undefined)
+            selectedRootNames.add(scripted.windowName);
+        for (const dynamicList of scripted.dynamicListDefinitions) {
+            if (dynamicList.entryContainer !== undefined)
+                selectedRootNames.add(dynamicList.entryContainer);
+            if (dynamicList.countryScopeEntryContainer !== undefined)
+                selectedRootNames.add(dynamicList.countryScopeEntryContainer);
+        }
+    }
+    const pending = graph.elements
+        .filter(({ name }) => selectedRootNames.has(name))
+        .map(({ id }) => id);
     const selected = new Map();
     while (pending.length > 0) {
         const id = pending.pop();
@@ -276,8 +327,8 @@ function localisationIconSpriteCandidates(token) {
     const normalized = token.startsWith('GFX_') ? token : `GFX_${token}`;
     return [...new Set([normalized, `${normalized}_texticon`, `${normalized}_text_icon`])];
 }
-function referencedAssetPatternsForWindow(graph, windowName) {
-    const spriteNames = new Set();
+function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = []) {
+    const spriteNames = new Set(additionalSpriteNames);
     const fontNames = new Set();
     const textValues = new Set();
     for (const element of selectedElements(graph, windowName)) {
@@ -326,6 +377,15 @@ function referencedAssetPatternsForWindow(graph, windowName) {
     ];
     return [...new Set(references.flatMap(referenceVariants))].sort((left, right) => compareCodeUnits(left, right));
 }
+function scenarioSpriteNames(scenarios) {
+    return [
+        ...new Set(scenarios.flatMap(({ scriptedGui }) => Object.entries(scriptedGui)
+            .filter(([key, value]) => typeof value === 'string' &&
+            value.startsWith('GFX_') &&
+            (key.endsWith('.image') || !key.includes('.')))
+            .map(([, value]) => value))),
+    ].sort((left, right) => compareCodeUnits(left, right));
+}
 function bmFontPagePatterns(files) {
     const references = files.flatMap((file) => {
         if (!file.relativePath.toLowerCase().endsWith('.fnt') || file.shadowedBy !== undefined)
@@ -333,7 +393,9 @@ function bmFontPagePatterns(files) {
         const metrics = parseBmFont(file.bytes.toString('utf8'));
         if (metrics === undefined)
             return [];
-        return metrics.pages.map((page) => path.posix.join(path.posix.dirname(file.relativePath), page));
+        const directory = path.posix.dirname(file.relativePath);
+        const sourceStem = file.relativePath.slice(0, -path.posix.extname(file.relativePath).length);
+        return [...metrics.pages.map((page) => path.posix.join(directory, page)), `${sourceStem}.dds`];
     });
     return [...new Set(references.flatMap(referenceVariants))].sort((left, right) => compareCodeUnits(left, right));
 }
@@ -343,14 +405,17 @@ function mergeScannedFiles(...groups) {
         byDisplayPath.set(file.displayPath, file);
     return [...byDisplayPath.values()].sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
 }
-function withGraphDiagnostics(graph, validation) {
-    const hard = graph.diagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker');
+function withGraphDiagnostics(graph, validation, selectedSourceIds = []) {
+    const graphDiagnostics = selectedSourceIds.length === 0
+        ? graph.diagnostics
+        : projectGuiGraphForArtifact(graph, selectedSourceIds).graph.diagnostics;
+    const hard = graphDiagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker');
     const diagnostics = new DiagnosticCollector(GUI_VALIDATION_MAX_DIAGNOSTICS, {
         code: 'GUI_VALIDATION_DIAGNOSTICS_TRUNCATED',
         category: 'layout',
         message: 'Combined GUI source and validation diagnostics exceeded the fixed result ceiling',
     });
-    diagnostics.pushMany(graph.diagnostics);
+    diagnostics.pushMany(graphDiagnostics);
     diagnostics.pushMany(validation.diagnostics);
     return {
         diagnostics: sortDiagnostics(diagnostics.values()),
@@ -517,6 +582,7 @@ export class ScriptedGuiStudio {
     transactions;
     scanner;
     artifacts;
+    #graphCache = new Map();
     constructor(engineOrResolver, transactions, scanner = new WorkspaceScanner(), artifacts = new ArtifactStore()) {
         this.engine =
             engineOrResolver instanceof CoreEngine
@@ -531,6 +597,32 @@ export class ScriptedGuiStudio {
         this.scanner = this.engine.scanner;
         this.artifacts = this.engine.artifacts;
     }
+    graphForFiles(files, scope) {
+        const key = `${scope}:${hashCanonical(files.map(({ displayPath, sha256, shadowedBy }) => ({
+            displayPath,
+            sha256,
+            ...(shadowedBy === undefined ? {} : { shadowedBy }),
+        })))}`;
+        const cached = this.#graphCache.get(key);
+        if (cached !== undefined) {
+            this.#graphCache.delete(key);
+            this.#graphCache.set(key, cached);
+            return cached;
+        }
+        const retainedFiles = [...files];
+        const scanned = {
+            files: retainedFiles,
+            graph: buildGuiSourceGraph(retainedFiles, this.engine.indexFiles(retainedFiles)),
+        };
+        this.#graphCache.set(key, scanned);
+        while (this.#graphCache.size > 8) {
+            const oldest = this.#graphCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#graphCache.delete(oldest);
+        }
+        return scanned;
+    }
     async scan(workspaceId, principal, signal, languages = ['l_english']) {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
@@ -543,16 +635,36 @@ export class ScriptedGuiStudio {
         ]);
         signal?.throwIfAborted();
         const files = mergeScannedFiles(snapshot.files, localisationFiles);
-        return {
-            files,
-            graph: buildGuiSourceGraph(files, snapshot.index),
-        };
+        return this.graphForFiles(files, `workspace:${workspaceId}`);
     }
-    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english']) {
-        const definitions = await this.scan(workspaceId, principal, signal, languages);
-        assertTargetWindowAvailable(definitions.graph, windowName);
+    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = []) {
         const workspace = this.resolver.get(workspaceId, principal);
-        const referencedPatterns = referencedAssetPatternsForWindow(definitions.graph, windowName);
+        const layoutPatterns = guiLayoutPatterns(workspace);
+        const overlayLayouts = await this.engine.scan(workspaceId, {
+            patterns: layoutPatterns,
+            rootKinds: ['mod', 'dependency', 'fixture'],
+        }, principal, signal);
+        let layoutFiles = overlayLayouts.files;
+        let layoutGraph = this.graphForFiles(layoutFiles, `layout:${workspaceId}`).graph;
+        if (!layoutGraph.elements.some(({ name }) => name === windowName)) {
+            const gameLayouts = await this.engine.scan(workspaceId, { patterns: layoutPatterns, rootKinds: ['game'] }, principal, signal);
+            const gameGraph = this.graphForFiles(gameLayouts.files, `game-layout:${workspaceId}`).graph;
+            const selectedPaths = new Set(gameGraph.elements
+                .filter(({ name }) => name === windowName)
+                .map(({ sourcePath }) => sourcePath));
+            layoutFiles = mergeScannedFiles(layoutFiles, gameLayouts.files.filter(({ displayPath }) => selectedPaths.has(displayPath)));
+            layoutGraph = this.graphForFiles(layoutFiles, `layout:${workspaceId}`).graph;
+        }
+        if (!layoutGraph.elements.some(({ name }) => name === windowName))
+            assertTargetWindowAvailable(layoutGraph, windowName);
+        const [linkedDefinitions, localisation] = await Promise.all([
+            this.engine.scan(workspaceId, { patterns: guiLinkedDefinitionPatterns(workspace) }, principal, signal),
+            this.engine.scan(workspaceId, { patterns: guiLocalisationPatterns(workspace, languages) }, principal, signal),
+        ]);
+        const definitionFiles = mergeScannedFiles(layoutFiles, linkedDefinitions.files, localisation.files);
+        const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`);
+        assertTargetWindowAvailable(definitions.graph, windowName);
+        const referencedPatterns = referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames);
         const exactReferenced = referencedPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -586,23 +698,24 @@ export class ScriptedGuiStudio {
         const fontPages = mergeScannedFiles(exactFontPages, fallbackFontPages);
         signal?.throwIfAborted();
         const files = mergeScannedFiles(definitions.files, referenced, fontPages);
-        return { files, graph: buildGuiSourceGraph(files, this.engine.indexFiles(files)) };
+        return this.graphForFiles(files, `window:${workspaceId}:${windowName}`);
     }
     async lint(input) {
         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 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);
+        const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
         const relatedScenes = [];
         for (const related of relatedScenarios) {
             input.signal?.throwIfAborted();
             relatedScenes.push(await buildGuiScene(scanned.graph, scanned.files, input.windowName, related, catalog));
         }
-        const validation = withGraphDiagnostics(scanned.graph, await validateGuiScene(scanned.graph, scene, scanned.files, relatedScenes, catalog));
+        const validationGraph = projectGuiGraphForArtifact(scanned.graph, [scene, ...relatedScenes].flatMap(({ elements }) => elements.map(({ sourceId }) => sourceId))).graph;
+        const validation = withGraphDiagnostics(validationGraph, await validateGuiScene(validationGraph, scene, scanned.files, relatedScenes, catalog));
         return { scene, graph: scanned.graph, validation };
     }
     async compare(input) {
@@ -610,10 +723,11 @@ export class ScriptedGuiStudio {
         const budget = new RenderBudget();
         const beforeScenario = parsePreviewScenario(input.before);
         const afterScenario = parsePreviewScenario(input.after);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language]);
-        const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget);
-        const before = await buildGuiScene(scanned.graph, scanned.files, input.windowName, beforeScenario, catalog);
-        const after = await buildGuiScene(scanned.graph, scanned.files, input.windowName, afterScenario, catalog);
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]));
+        const beforeCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, beforeScenario.language);
+        const afterCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, afterScenario.language);
+        const before = await buildGuiScene(scanned.graph, scanned.files, input.windowName, beforeScenario, beforeCatalog);
+        const after = await buildGuiScene(scanned.graph, scanned.files, input.windowName, afterScenario, afterCatalog);
         const [beforeRender, afterRender] = await Promise.all([
             renderGuiScene(before, ['full'], input.signal, budget),
             renderGuiScene(after, ['full'], input.signal, budget),
@@ -650,8 +764,8 @@ export class ScriptedGuiStudio {
             scenario.language,
             baselineScenario.language,
             ...relatedScenarios.map(({ language }) => language),
-        ]);
-        const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget);
+        ], scenarioSpriteNames([scenario, baselineScenario, ...relatedScenarios]));
+        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);
         const scenarioScenes = [scene];
@@ -715,12 +829,19 @@ 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, scenarioScenes.slice(1), catalog);
+        const renderedSourceIds = [
+            ...scenarioScenes,
+            ...stateScenes,
+            ...resolutionScenes,
+            baselineScene,
+        ].flatMap(({ elements }) => elements.map(({ sourceId }) => sourceId));
+        const validationGraph = projectGuiGraphForArtifact(scanned.graph, renderedSourceIds).graph;
+        const validation = await validateGuiScene(validationGraph, 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 completeValidation = withGraphDiagnostics(validationGraph, 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);
@@ -746,6 +867,9 @@ export class ScriptedGuiStudio {
                 .toBuffer(),
         ]);
         const slug = safeSlug(input.windowName);
+        const projectedArtifactGraph = projectGuiGraphForArtifact(scanned.graph, [
+            ...new Set([...scenarioScenes, ...stateScenes, ...resolutionScenes, baselineScene].flatMap(({ elements }) => elements.map(({ sourceId }) => sourceId))),
+        ]);
         const writes = [];
         const add = (name, mimeType, content, kind, scenarioScenes = [scene], metadata = {}) => {
             input.signal?.throwIfAborted();
@@ -764,7 +888,13 @@ export class ScriptedGuiStudio {
         add(`${slug}-layout.json`, 'application/json', render.layoutJson, 'gui-layout-json');
         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}-source-graph.json`, 'application/json', `${canonicalJson({
+            schemaVersion: 1,
+            graph: projectedArtifactGraph.graph,
+            ...(projectedArtifactGraph.projection === undefined
+                ? {}
+                : { graphProjection: projectedArtifactGraph.projection }),
+        })}\n`, 'gui-source-graph');
         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);
@@ -910,9 +1040,10 @@ export class ScriptedGuiStudio {
             });
         if ((input.windowName === undefined) !== (input.scenario === undefined))
             throw new Error('GUI visual preflight requires both windowName and scenario.');
+        const previewScenario = input.scenario === undefined ? undefined : parsePreviewScenario(input.scenario);
         const initiallyScanned = input.windowName === undefined
             ? await this.scan(input.workspaceId, input.principal, input.signal)
-            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [parsePreviewScenario(input.scenario).language]);
+            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]));
         const exactTargets = await this.scanner.scan(workspace, {
             patterns: prepared.map(({ relativePath }) => relativePath),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
@@ -970,8 +1101,9 @@ export class ScriptedGuiStudio {
             const proposedScene = await buildGuiScene(proposedGraph, proposedFiles, input.windowName, scenario, proposedCatalog);
             const proposedRender = await renderGuiScene(proposedScene, ['full'], input.signal, renderBudget);
             const proposedImage = fullImage(proposedRender);
-            const proposedValidation = await validateGuiScene(proposedGraph, proposedScene, proposedFiles, [], proposedCatalog);
-            preflightDiagnostics.push(...proposedGraph.diagnostics, ...proposedScene.diagnostics, ...proposedValidation.diagnostics);
+            const proposedValidationGraph = projectGuiGraphForArtifact(proposedGraph, proposedScene.elements.map(({ sourceId }) => sourceId)).graph;
+            const proposedValidation = await validateGuiScene(proposedValidationGraph, proposedScene, proposedFiles, [], proposedCatalog);
+            preflightDiagnostics.push(...proposedValidationGraph.diagnostics, ...proposedScene.diagnostics, ...proposedValidation.diagnostics);
             const visualPassed = proposedValidation.checks.every(({ passed }) => passed) &&
                 !preflightDiagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
             preflightChecks.push(...proposedValidation.checks, {

package/dist/hoi4_agent_tools/gui/validators.js

@@ -301,8 +301,23 @@ function actionElementName(action) {
         .replace(/_(?:visible|enabled)$/u, '');
 }
 function attachedScriptedGuis(graph, scene) {
-    return graph.scriptedGuis.filter((definition) => definition.windowName === scene.windowName ||
-        definition.parentWindowName === scene.windowName);
+    const attachedNames = new Set(graph.scriptedGuis
+        .filter((definition) => definition.windowName === scene.windowName ||
+        definition.parentWindowName === scene.windowName)
+        .map(({ name }) => name));
+    let added = true;
+    while (added) {
+        added = false;
+        for (const definition of graph.scriptedGuis) {
+            if (definition.parentScriptedGui === undefined ||
+                !attachedNames.has(definition.parentScriptedGui) ||
+                attachedNames.has(definition.name))
+                continue;
+            attachedNames.add(definition.name);
+            added = true;
+        }
+    }
+    return graph.scriptedGuis.filter(({ name }) => attachedNames.has(name));
 }
 function normalizedCostResource(value) {
     const normalized = value.toLowerCase().replace(/_icon$/u, '');
@@ -410,8 +425,6 @@ function validateOverlapAndGeometry(scene, diagnostics, work) {
         if (element.clickable && element.visible && !sameRect(element.rect, element.unclippedRect)) {
             diagnostics.push(issue('GUI_CLICK_BOUNDS_MISMATCH', 'warning', 'design', `${element.name} has visible/clipped bounds that differ from its source click rectangle.`, element));
         }
-        if (element.clickable && !element.visible)
-            diagnostics.push(issue('GUI_INVISIBLE_CLICK_BLOCKER', 'error', 'design', `${element.name} remains clickable while invisible in this scenario.`, element));
     }
     const visiblePairCount = (visible.length * (visible.length - 1)) / 2;
     if (work.admitPairs(visiblePairCount, 'GUI overlap validation', diagnostics)) {
@@ -547,20 +560,16 @@ function validateReferencesAndScript(graph, scene, diagnostics) {
             diagnostics.push(issue('GUI_RENDER_FIELD_UNSUPPORTED', 'info', 'rendering', `${element.name}.${field} is preserved in source but not reliably modelled.`, element));
     }
     const validContexts = new Set([
-        'country',
-        'state',
-        'unit_leader',
-        'operative',
-        'character',
-        'division',
+        'player_context',
+        'selected_country_context',
+        'selected_state_context',
         'decision',
         'decision_category',
-        'national_focus',
-        'shared_focus',
-        'technology',
-        'equipment',
-        'military_industrial_organization',
-        'special_project',
+        'diplomatic_action',
+        'diplomacy_target_context',
+        'national_focus_context',
+        'country_mapicon',
+        'state_mapicon',
     ]);
     const names = new Set(graph.scriptedGuis.map(({ name }) => name));
     const windowNames = new Set(graph.elements.map(({ name }) => name));
@@ -576,10 +585,10 @@ function validateReferencesAndScript(graph, scene, diagnostics) {
         }
         else if (!validContexts.has(scripted.contextType)) {
             diagnostics.push({
-                code: 'GUI_SCRIPTED_CONTEXT_INVALID',
-                severity: 'error',
+                code: 'GUI_SCRIPTED_CONTEXT_UNKNOWN',
+                severity: 'warning',
                 category: 'reference',
-                message: `Scripted GUI ${scripted.name} uses unknown context_type ${scripted.contextType}.`,
+                message: `Scripted GUI ${scripted.name} uses context_type ${scripted.contextType}, which is not in the renderer's installed-game and documented context inventory.`,
                 ...(scripted.location === undefined ? {} : { location: scripted.location }),
             });
         }
@@ -612,10 +621,20 @@ function validateReferencesAndScript(graph, scene, diagnostics) {
     if (attached.length > 0) {
         const effects = new Set(attached.flatMap(({ effects }) => effects.map(actionElementName)));
         const triggers = new Set(attached.flatMap(({ triggers }) => triggers.map(actionElementName)));
+        const elementsById = new Map(graph.elements.map((element) => [element.id, element]));
         for (const button of scene.elements.filter(({ elementType }) => /button/iu.test(elementType))) {
-            if (!effects.has(button.name))
-                diagnostics.push(issue('GUI_BUTTON_EFFECT_MISSING', 'error', 'reference', `Button ${button.name} has no matching scripted GUI click effect.`, button));
-            if (!triggers.has(button.name))
+            const source = elementsById.get(button.sourceId);
+            const tooltipOnly = !effects.has(button.name) &&
+                !triggers.has(button.name) &&
+                (typeof source?.attributes.pdx_tooltip === 'string' ||
+                    typeof source?.attributes.pdx_tooltip_delayed === 'string') &&
+                source.attributes.text === undefined &&
+                source.attributes.buttonText === undefined;
+            if (!effects.has(button.name) && !triggers.has(button.name) && !tooltipOnly)
+                diagnostics.push(issue('GUI_BUTTON_EFFECT_MISSING', 'error', 'reference', `Button ${button.name} has no matching scripted GUI click effect or tooltip-only role.`, button));
+            if (triggers.has(button.name) && !effects.has(button.name))
+                diagnostics.push(issue('GUI_BUTTON_EFFECT_MISSING', 'warning', 'reference', `Button ${button.name} is controlled by a scripted GUI trigger but has no matching click effect.`, button));
+            if (effects.has(button.name) && !triggers.has(button.name))
                 diagnostics.push(issue('GUI_BUTTON_TRIGGER_MISSING', 'warning', 'reference', `Button ${button.name} has no matching scripted GUI visibility/enabled trigger.`, button));
         }
         for (const scripted of attached.filter(({ effects, aiEnabled }) => effects.length > 0 && !aiEnabled)) {
@@ -1036,13 +1055,15 @@ function validationResult(diagnostics, codes) {
     return {
         diagnostics: sorted,
         checks: codes.map((code) => {
-            const count = sorted.filter((diagnostic) => diagnostic.code === code).length;
+            const matching = sorted.filter((diagnostic) => diagnostic.code === code);
+            const count = matching.length;
+            const blockingCount = matching.filter(({ severity }) => severity === 'error' || severity === 'blocker').length;
             return {
                 id: code.toLowerCase(),
-                passed: count === 0,
+                passed: blockingCount === 0,
                 message: count === 0
                     ? `${code} not detected.`
-                    : `${code} detected ${count} time${count === 1 ? '' : 's'}.`,
+                    : `${code} detected ${count} time${count === 1 ? '' : 's'}${blockingCount === 0 ? ' as non-blocking findings' : `, including ${blockingCount} blocking finding${blockingCount === 1 ? '' : 's'}`}.`,
             };
         }),
     };
@@ -1112,7 +1133,6 @@ export async function validateGuiScene(graph, scene, files, relatedScenes = [],
         'GUI_INVALID_SIZE',
         'GUI_CHILD_OUTSIDE_CLIPPED_PARENT',
         'GUI_CLICK_BOUNDS_MISMATCH',
-        'GUI_INVISIBLE_CLICK_BLOCKER',
         'GUI_CONFLICTING_CLICK_REGIONS',
         'GUI_MISSING_SPRITE',
         'GUI_MISSING_TEXTURE',
@@ -1122,7 +1142,7 @@ export async function validateGuiScene(graph, scene, files, relatedScenes = [],
         'GUI_ANIMATION_SHEET_DIMENSION_INVALID',
         'GUI_ANIMATION_STATIC_FALLBACK_MISSING',
         'GUI_PARENT_WINDOW_INVALID',
-        'GUI_SCRIPTED_CONTEXT_INVALID',
+        'GUI_SCRIPTED_CONTEXT_UNKNOWN',
         'GUI_Z_ORDER_RISK',
         'GUI_SCROLL_ROW_CUTOFF',
         'GUI_RESOLUTION_DRIFT',

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -8,7 +8,7 @@ import { registerEventTools } from '../tools/event.js';
 import { registerTechnologyTools } from '../tools/technology.js';
 import { registerProbabilityTools } from '../tools/probability.js';
 import { registerMcpResources } from '../resources/register.js';
-export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Long GUI calls emit periodic progress heartbeats when the client requests progress. Large evidence is linked as resources.';
 export function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,

package/dist/hoi4_agent_tools/mcp/server/progress.js

@@ -1,9 +1,18 @@
+/**
+ * Interval used for long-running MCP operations. It is shorter than the request timeout used by
+ * common MCP clients, while still keeping notification traffic negligible for ordinary calls.
+ */
+export const PROGRESS_HEARTBEAT_INTERVAL_MS = 10_000;
 export function progressReporter(extra) {
     let latest = Number.NEGATIVE_INFINITY;
+    let latestTotal = 1;
+    let latestMessage = '';
     return {
         signal: extra.signal,
         async report(progress, total, message) {
             extra.signal.throwIfAborted();
+            latestTotal = total;
+            latestMessage = message;
             const normalized = Math.max(latest, Math.min(progress, total));
             const progressToken = extra._meta?.progressToken;
             if (progressToken === undefined)
@@ -16,5 +25,56 @@ export function progressReporter(extra) {
                 params: { progressToken, progress: normalized, total, message },
             });
         },
+        async pulse(message = latestMessage) {
+            extra.signal.throwIfAborted();
+            const progressToken = extra._meta?.progressToken;
+            if (progressToken === undefined)
+                return;
+            await extra.sendNotification({
+                method: 'notifications/progress',
+                params: {
+                    progressToken,
+                    progress: Number.isFinite(latest) ? latest : 0,
+                    total: latestTotal,
+                    message,
+                },
+            });
+        },
+    };
+}
+/**
+ * Keep an MCP request alive while a domain service is in a long, opaque asynchronous stage.
+ * Progress notifications are best-effort: a disconnected client must not turn a successful
+ * server operation into a partial result, while the request's AbortSignal still cancels work.
+ */
+export async function withProgressHeartbeat(operation, reporter, message, intervalMs = PROGRESS_HEARTBEAT_INTERVAL_MS) {
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+        throw new RangeError('Progress heartbeat interval must be a positive finite number');
+    }
+    reporter.signal.throwIfAborted();
+    let active = true;
+    let inFlight = false;
+    const tick = () => {
+        if (!active || inFlight || reporter.signal.aborted)
+            return;
+        inFlight = true;
+        void reporter
+            .pulse(message)
+            .catch(() => undefined)
+            .finally(() => {
+            inFlight = false;
+        });
     };
+    const timer = setInterval(tick, intervalMs);
+    timer.unref();
+    // Tell the client which opaque stage has started immediately. Waiting for the first interval
+    // leaves short-but-expensive stages silent and makes keep-alive behavior scheduler-dependent.
+    tick();
+    try {
+        return await (typeof operation === 'function' ? operation() : operation);
+    }
+    finally {
+        active = false;
+        clearInterval(timer);
+    }
 }