hoi4-agent-tools 4.0.3 → 4.0.5

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

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { compareCodeUnits, deterministicId } from '../core/canonical.js';
 import { DiagnosticCollector } from '../core/diagnostic-collector.js';
 import { sortDiagnostics } from '../core/diagnostics.js';
+import { SymbolIndex } from '../core/index.js';
 import { ServiceError } from '../core/result.js';
 import { GUI_GRAPH_MAX_EDGES, GUI_GRAPH_MAX_ELEMENTS, GUI_GRAPH_MAX_NODES } from './limits.js';
 import { assignments, childBlocks, firstScalar, locationFor, nodeLocation, parseClausewitz, parseLocalisation, } from '../core/source/index.js';
@@ -118,7 +119,7 @@ export function guiElementAttributeFidelity(key, elementType) {
     if (elementType?.toLowerCase() === 'extendedscrollbartype' &&
         ['horizontal', 'slider', 'track', 'decreaseButton', 'increaseButton'].some((candidate) => candidate.toLowerCase() === key.toLowerCase()))
         return 'modelled';
-    if (/^(?:containerwindowtype|windowtype)$/iu.test(elementType ?? '') &&
+    if (/^(?:containerwindowtype|windowtype|expandedwindow)$/iu.test(elementType ?? '') &&
         ['verticalScrollbar', 'horizontalScrollbar', 'autohide_scrollbars', 'margin'].some((candidate) => candidate.toLowerCase() === key.toLowerCase()))
         return 'structural';
     if (elementType?.toLowerCase() === 'scrollbartype' &&
@@ -297,9 +298,12 @@ function nestedSizeFrom(block, key) {
 function raw(document, node) {
     return document.text.slice(node.start, node.end);
 }
-function isGuiElement(assignment) {
+function isGuiElement(assignment, parentType) {
     if (assignment.value.type !== 'block')
         return false;
+    if (parentType?.toLowerCase() === 'dropdownboxtype' &&
+        /^(?:expandedwindow|expandbutton)$/iu.test(assignment.key.value))
+        return true;
     if (explicitGuiElementTypes.has(assignment.key.value.toLowerCase()))
         return true;
     return (/type$/iu.test(assignment.key.value) && firstScalar(assignment.value, 'name') !== undefined);
@@ -362,11 +366,11 @@ function indexGuiElements(document, file, fileNodeId, nodes, edges, elements) {
     const constants = constantsFor(document);
     const firstFileElement = elements.length;
     let order = 0;
-    const walk = (block, parentId) => {
+    const walk = (block, parentId, parentType) => {
         for (const assignment of assignments(block)) {
             if (assignment.value.type !== 'block')
                 continue;
-            if (isGuiElement(assignment)) {
+            if (isGuiElement(assignment, parentType)) {
                 const name = firstScalar(assignment.value, 'name')?.value;
                 if (name === undefined)
                     continue;
@@ -385,7 +389,7 @@ function indexGuiElements(document, file, fileNodeId, nodes, edges, elements) {
                     childIds: [],
                     attributes: attributes,
                     unsupportedAttributes: assignments(assignment.value)
-                        .filter((child) => !isGuiElement(child))
+                        .filter((child) => !isGuiElement(child, assignment.key.value))
                         .map(({ key }) => key.value)
                         .filter((key) => guiElementAttributeFidelity(key, assignment.key.value) === 'unsupported')
                         .sort((a, b) => compareCodeUnits(a, b)),
@@ -408,7 +412,7 @@ function indexGuiElements(document, file, fileNodeId, nodes, edges, elements) {
                 addEdge(edges, 'contains', parentId ?? fileNodeId, id, true, {}, element.location);
                 if (parentId !== undefined)
                     addEdge(edges, 'parent', id, parentId, true, {}, element.location);
-                walk(assignment.value, id);
+                walk(assignment.value, id, assignment.key.value);
             }
             else {
                 walk(assignment.value, parentId);
@@ -1306,7 +1310,8 @@ function referenceLabel(edge) {
         return String(value);
     return value === undefined ? edge.to : JSON.stringify(value);
 }
-export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKeys = []) {
+export function buildGuiSourceGraph(files, providedIndex, additionalLocalisationKeys = [], limits = {}) {
+    const sharedIndex = providedIndex ?? new SymbolIndex();
     const activeFiles = files.filter(({ shadowedBy }) => shadowedBy === undefined);
     const nodes = [];
     const edges = [];
@@ -1323,25 +1328,6 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
         category: 'layout',
         message: 'GUI source graph diagnostics exceeded the fixed global result ceiling',
     });
-    diagnostics.pushMany(sharedIndex.diagnostics);
-    if (!sharedIndex.complete) {
-        diagnostics.push({
-            code: 'GUI_INVENTORY_PARTIAL',
-            severity: 'warning',
-            category: 'reference',
-            message: sharedIndex.skippedSourceCount === 0
-                ? 'The GUI inventory is incomplete because the shared index reached a fixed record limit'
-                : `The GUI inventory skipped ${sharedIndex.skippedSourceCount} over-limit source${sharedIndex.skippedSourceCount === 1 ? '' : 's'}`,
-            details: {
-                skippedSourceCount: sharedIndex.skippedSourceCount,
-                retainedSkippedSources: sharedIndex.skippedSources.length,
-                skippedSources: sharedIndex.skippedSources.slice(0, 10).map(({ path, reasonCodes }) => ({
-                    path,
-                    reasonCodes,
-                })),
-            },
-        });
-    }
     const sourceHashes = {};
     const textureNodes = new Map();
     const fontAssetNodes = new Map();
@@ -1423,13 +1409,20 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
         if (kind === undefined || fileNodeId === undefined) {
             if (/\.(?:txt|gui|gfx)$/u.test(normalized)) {
                 const document = parseClausewitz(file.bytes, file.displayPath);
+                if (providedIndex === undefined &&
+                    !sharedIndex.recordSourceCoverage(file, document.diagnostics))
+                    continue;
                 if (file.rootKind === 'mod' || file.rootKind === 'fixture')
                     diagnostics.pushMany(document.diagnostics);
-                indexDecisionEntries(document, file, nodes, pendingDecisionEdges);
+                if (/^common\/decision(?:s|_categories)\//u.test(normalized))
+                    indexDecisionEntries(document, file, nodes, pendingDecisionEdges);
             }
             continue;
         }
         const document = parseClausewitz(file.bytes, file.displayPath);
+        if (providedIndex === undefined &&
+            !sharedIndex.recordSourceCoverage(file, document.diagnostics))
+            continue;
         if (file.rootKind === 'mod' || file.rootKind === 'fixture')
             diagnostics.pushMany(document.diagnostics);
         if (kind === 'gui_file')
@@ -1451,14 +1444,22 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
     const referencedLocalisationKeys = referencedGuiLocalisationKeys(elements, scriptedLocalisation);
     for (const key of additionalLocalisationKeys)
         referencedLocalisationKeys.add(key);
+    const maximumCandidates = Math.min(GUI_GRAPH_MAX_NODES, limits.maximumLocalisationCandidates ?? GUI_GRAPH_MAX_NODES);
+    if (!Number.isSafeInteger(maximumCandidates) || maximumCandidates < 1)
+        throw new ServiceError('GUI_LOCALISATION_BUDGET_INVALID', 'Localisation candidate limit must be a positive safe integer');
+    let candidateCount = 0;
+    const localisationCandidates = new Map();
     for (const { file, fileNodeId } of localisationFiles.sort((left, right) => right.file.loadOrder - left.file.loadOrder ||
         compareCodeUnits(left.file.displayPath, right.file.displayPath))) {
         const document = parseLocalisation(file.bytes, file.displayPath);
+        if (providedIndex === undefined &&
+            !sharedIndex.recordSourceCoverage(file, document.diagnostics))
+            continue;
         if (file.rootKind === 'mod' || file.rootKind === 'fixture')
             diagnostics.pushMany(document.diagnostics);
         for (const entry of document.entries) {
-            if (!referencedLocalisationKeys.has(entry.key))
-                continue;
+            if (++candidateCount > maximumCandidates)
+                throw new ServiceError('GUI_LOCALISATION_BUDGET_BLOCKED', 'Localisation dependency inventory exceeds the fixed candidate ceiling', { maximumCandidates });
             const value = {
                 key: entry.key,
                 language: entry.language,
@@ -1466,21 +1467,55 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
                 sourcePath: file.displayPath,
                 location: locationFor(file.displayPath, document.lineIndex, entry.start, entry.end),
             };
+            const candidates = localisationCandidates.get(entry.key) ?? [];
+            candidates.push({ value, fileNodeId });
+            localisationCandidates.set(entry.key, candidates);
+        }
+    }
+    const pendingKeys = [...referencedLocalisationKeys];
+    for (const key of pendingKeys) {
+        for (const { value, fileNodeId } of localisationCandidates.get(key) ?? []) {
             addDomainEntry(localisation, value, 'localisation');
             const id = deterministicId('gui_loc', value);
             addNode(nodes, {
                 id,
                 kind: 'localisation',
-                name: entry.key,
-                path: file.displayPath,
+                name: key,
+                path: value.sourcePath,
                 ...(value.location === undefined ? {} : { location: value.location }),
-                metadata: { language: entry.language, value: entry.value },
+                metadata: { language: value.language, value: value.value },
             });
             addEdge(edges, 'contains', fileNodeId, id, true, {}, value.location);
+            for (const match of value.value.matchAll(/\$([A-Za-z0-9_.-]+)(?:\|[^$]*)?\$/gu)) {
+                const dependency = match[1];
+                if (!referencedLocalisationKeys.has(dependency)) {
+                    referencedLocalisationKeys.add(dependency);
+                    pendingKeys.push(dependency);
+                }
+            }
         }
     }
     linkGraph(nodes, edges, elements, sprites, fonts, scriptedGuis, scriptedLocalisation, localisation, textureNodes, fontAssetNodes, pendingDecisionEdges);
     linkAnimationSources(nodes, edges, animationSources, sprites, textureNodes, animationFrameNodes);
+    diagnostics.pushMany(sharedIndex.diagnostics);
+    if (!sharedIndex.complete) {
+        diagnostics.push({
+            code: 'GUI_INVENTORY_PARTIAL',
+            severity: 'warning',
+            category: 'reference',
+            message: sharedIndex.skippedSourceCount === 0
+                ? 'The GUI inventory is incomplete because the shared index reached a fixed record limit'
+                : `The GUI inventory skipped ${sharedIndex.skippedSourceCount} over-limit source${sharedIndex.skippedSourceCount === 1 ? '' : 's'}`,
+            details: {
+                skippedSourceCount: sharedIndex.skippedSourceCount,
+                retainedSkippedSources: sharedIndex.skippedSources.length,
+                skippedSources: sharedIndex.skippedSources.slice(0, 10).map(({ path, reasonCodes }) => ({
+                    path,
+                    reasonCodes,
+                })),
+            },
+        });
+    }
     markPartialReferenceEdges(edges, sharedIndex);
     diagnostics.pushMany(referenceDiagnostics(edges));
     if (nodes.length > GUI_GRAPH_MAX_NODES ||

package/dist/hoi4_agent_tools/gui/studio.js

@@ -9,6 +9,7 @@ import { CoreEngine } from '../core/engine.js';
 import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
 import { assertRenderDimensions, RenderBudget, RENDER_MAX_PIXELS } from '../core/render-budget.js';
 import { escapeFileGlob } from '../core/file-glob.js';
+import { renderStage } from '../core/render-progress.js';
 import { ServiceError } from '../core/result.js';
 import { WorkspaceScanner } from '../core/scanner.js';
 import { applyReplacements, decodeSource, encodeSource, parseClausewitz, parseLocalisation, SOURCE_MAX_BYTES, sourcePartialLimitDiagnostics, } from '../core/source/index.js';
@@ -22,7 +23,7 @@ import { projectGuiGraphForArtifact } from './inspection-artifact.js';
 import { buildGuiScene } from './layout.js';
 import { GUI_VALIDATION_MAX_DIAGNOSTICS } from './limits.js';
 import { compareGuiImages, galleryDimensions, renderGallerySvg, renderGuiScene, } from './renderer.js';
-import { generateGuiPreviewScenarios, resolveScenarioScriptedLocalisation, } from './scenario-generator.js';
+import { generatedCountryTags, generateGuiPreviewScenarios, resolveScenarioScriptedLocalisation, } from './scenario-generator.js';
 import { parseGeneratedScenarioOptions, parsePreviewScenario } from './scenario.js';
 import { buildGuiSourceGraph } from './source-graph.js';
 import { assertGuiSourcePatchesSafe } from './source-patch.js';
@@ -242,13 +243,17 @@ function referenceVariants(value) {
     return candidates;
 }
 const FALLBACK_NAMES_PER_PATTERN = 100;
-function basenameFallbackPatterns(exactPaths, exactFiles) {
+function basenameFallbackPatterns(exactPaths, exactFiles, assetRoots = ['gfx', 'interface', 'fonts']) {
     const resolved = new Set(exactFiles
         .filter(({ shadowedBy }) => shadowedBy === undefined)
         .map(({ relativePath }) => relativePath.replaceAll('\\', '/').toLowerCase()));
+    const stem = (value) => value.toLowerCase().replace(/\.(?:png|bmp|tga|dds|svg|fnt|ttf|otf|woff2?)$/u, '');
+    const resolvedStems = new Set([...resolved].map(stem));
     const names = [
         ...new Set(exactPaths
-            .filter((candidate) => !/[*?[\]{}!]/u.test(candidate) && !resolved.has(candidate.toLowerCase()))
+            .filter((candidate) => !/[*?[\]{}!]/u.test(candidate) &&
+            !resolved.has(candidate.toLowerCase()) &&
+            !resolvedStems.has(stem(candidate)))
             .map((candidate) => path.posix.basename(candidate))),
     ].sort((left, right) => compareCodeUnits(left, right));
     // One brace group searches many names in a single bounded wildcard pattern, so a window
@@ -261,7 +266,9 @@ function basenameFallbackPatterns(exactPaths, exactFiles) {
         const chunk = grouped.slice(start, start + FALLBACK_NAMES_PER_PATTERN).map(escapeFileGlob);
         patterns.push(chunk.length === 1 ? `**/${chunk[0]}` : `**/{${chunk.join(',')}}`);
     }
-    return patterns.sort((left, right) => compareCodeUnits(left, right));
+    return [...new Set(assetRoots)]
+        .flatMap((root) => patterns.map((pattern) => `${escapeFileGlob(normalizeConfiguredRoot(root))}/${pattern}`))
+        .sort(compareCodeUnits);
 }
 function selectedElements(graph, windowName, additionalTemplateNames = []) {
     const byId = new Map(graph.elements.map((element) => [element.id, element]));
@@ -549,10 +556,14 @@ export function scenarioCountryFlagPatterns(scenarios) {
         for (const values of [
             scenario.values,
             scenario.scriptedGui,
+            scenario.country ?? {},
             ...Object.values(scenario.lists).flat(),
         ]) {
             for (const [key, value] of Object.entries(values)) {
-                if (key.endsWith('.countryTag') &&
+                if ((key.endsWith('.countryTag') ||
+                    key.endsWith('.tag') ||
+                    /(?:^|\.)GetFlag$/u.test(key) ||
+                    ['countryTag', 'GetTag', 'tag'].includes(key)) &&
                     typeof value === 'string' &&
                     /^[A-Za-z0-9_]{2,64}$/u.test(value))
                     tags.add(value.toUpperCase());
@@ -573,8 +584,14 @@ export function scenarioCountryFlagPatterns(scenarios) {
 function scenarioCountryHistoryPatterns(scenarios) {
     return scenarios.some(scenarioNeedsCountryHistory) ? ['history/countries/*.txt'] : [];
 }
-function scenarioCountryAssetPatterns(scenarios) {
-    return [...scenarioCountryFlagPatterns(scenarios), ...scenarioCountryHistoryPatterns(scenarios)];
+function scenarioCountryAssetPatterns(scenarios, generated = false) {
+    const flags = generated
+        ? [
+            ...scenarios,
+            ...generatedCountryTags.map((tag) => parsePreviewScenario({ id: `generated-${tag}`, country: { tag } })),
+        ]
+        : scenarios;
+    return [...scenarioCountryFlagPatterns(flags), ...scenarioCountryHistoryPatterns(scenarios)];
 }
 function bmFontPagePatterns(files) {
     const references = files.flatMap((file) => {
@@ -972,13 +989,9 @@ export class ScriptedGuiStudio {
             return cached;
         }
         const retainedFiles = [...files];
-        // The previous graph of this scope still indexes every unchanged file.
-        const previous = [...this.#graphCache].find(([existing]) => existing.startsWith(`${scope}:`))?.[1].index;
-        const index = this.engine.indexFiles(retainedFiles, previous);
         const scanned = {
             files: retainedFiles,
-            graph: buildGuiSourceGraph(retainedFiles, index, additionalLocalisationKeys),
-            index,
+            graph: buildGuiSourceGraph(retainedFiles, undefined, additionalLocalisationKeys),
         };
         // One graph per scope: a preview builds layout, game-layout and definition graphs, and a
         // single shared slot made each repeat call rebuild all of them.
@@ -1003,50 +1016,75 @@ export class ScriptedGuiStudio {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
         const [snapshot, localisationFiles] = await Promise.all([
-            this.engine.scan(workspaceId, { patterns: guiDefinitionPatterns(workspace) }, principal, signal),
+            this.scanner.scan(workspace, {
+                patterns: guiDefinitionPatterns(workspace),
+                ...(signal === undefined ? {} : { signal }),
+            }),
             this.scanner.scan(workspace, {
                 patterns: guiLocalisationPatterns(workspace, languages),
                 ...(signal === undefined ? {} : { signal }),
             }),
         ]);
         signal?.throwIfAborted();
-        const files = mergeScannedFiles(snapshot.files, localisationFiles);
+        const files = mergeScannedFiles(snapshot, localisationFiles);
         return this.graphForFiles(files, `workspace:${workspaceId}`);
     }
-    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = [], includeImmediateTooltip = false) {
+    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = [], includeImmediateTooltip = false, progress) {
+        const stage = (phase) => renderStage({
+            ...(signal === undefined ? {} : { signal }),
+            ...(progress === undefined ? {} : { progress }),
+        }, phase);
+        await stage('Scanning GUI layouts');
         const workspace = this.resolver.get(workspaceId, principal);
         const layoutPatterns = guiLayoutPatterns(workspace);
-        const overlayLayouts = await this.engine.scan(workspaceId, {
+        const overlayLayouts = await this.scanner.scan(workspace, {
             patterns: layoutPatterns,
             rootKinds: ['mod', 'dependency', 'fixture'],
-        }, principal, signal);
-        let layoutFiles = overlayLayouts.files;
+            ...(signal === undefined ? {} : { signal }),
+        });
+        let layoutFiles = overlayLayouts;
         let layoutGraph = this.graphForFiles(layoutFiles, `layout:${workspaceId}`).graph;
         const selectedLayoutElements = selectedElements(layoutGraph, windowName, additionalTemplateNames);
         const requiredNames = new Set([windowName, ...additionalTemplateNames]);
         for (const element of selectedLayoutElements)
             collectNamedAttributes(element.attributes, new Set(['verticalScrollbar', 'horizontalScrollbar', 'scrollbarType', 'scrollbartype']), requiredNames);
-        const availableNames = new Set(layoutGraph.elements.map(({ name }) => name));
+        // Scrollbar and row references name public templates, not private controls with the same name.
+        const availableNames = new Set(layoutGraph.elements.filter(({ parentId }) => parentId === undefined).map(({ name }) => name));
+        if (layoutGraph.elements.some(({ name }) => name === windowName))
+            availableNames.add(windowName);
         if ([...requiredNames].some((name) => !availableNames.has(name))) {
-            const gameLayouts = await this.engine.scan(workspaceId, { patterns: layoutPatterns, rootKinds: ['game', 'dlc'] }, principal, signal);
-            const gameGraph = this.graphForFiles(gameLayouts.files, `game-layout:${workspaceId}`).graph;
+            const gameLayouts = await this.scanner.scan(workspace, {
+                patterns: layoutPatterns,
+                rootKinds: ['game', 'dlc'],
+                ...(signal === undefined ? {} : { signal }),
+            });
+            const gameGraph = this.graphForFiles(gameLayouts, `game-layout:${workspaceId}`).graph;
             const selectedPaths = new Set(selectedElements(gameGraph, windowName, [...requiredNames]).map(({ sourcePath }) => sourcePath));
-            layoutFiles = mergeScannedFiles(layoutFiles, gameLayouts.files.filter(({ displayPath }) => selectedPaths.has(displayPath)));
+            layoutFiles = mergeScannedFiles(layoutFiles, gameLayouts.filter(({ displayPath }) => selectedPaths.has(displayPath)));
             layoutGraph = this.graphForFiles(layoutFiles, `merged-layout:${workspaceId}`).graph;
         }
         if (!layoutGraph.elements.some(({ name }) => name === windowName))
             assertTargetWindowAvailable(layoutGraph, windowName);
+        await stage('Scanning GUI definitions and localisation');
         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),
+            this.scanner.scan(workspace, {
+                patterns: guiLinkedDefinitionPatterns(workspace),
+                ...(signal === undefined ? {} : { signal }),
+            }),
+            this.scanner.scan(workspace, {
+                patterns: guiLocalisationPatterns(workspace, languages),
+                ...(signal === undefined ? {} : { signal }),
+            }),
         ]);
-        const definitionFiles = mergeScannedFiles(layoutFiles, linkedDefinitions.files, localisation.files);
+        const definitionFiles = mergeScannedFiles(layoutFiles, linkedDefinitions, localisation);
+        await stage('Building GUI source graph');
         const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`, additionalLocalisationKeys);
         assertTargetWindowAvailable(definitions.graph, windowName);
         const referencedPatterns = [
-            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames, includeImmediateTooltip),
+            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames, includeImmediateTooltip).filter((pattern) => !pattern.startsWith('gfx/flags/')),
             ...additionalAssetPatterns,
         ];
+        await stage('Loading selected GUI assets');
         const exactReferenced = referencedPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -1054,7 +1092,11 @@ export class ScriptedGuiStudio {
                 ...(signal === undefined ? {} : { signal }),
             });
         signal?.throwIfAborted();
-        const fallbackPatterns = basenameFallbackPatterns(referencedPatterns, exactReferenced);
+        const fallbackPatterns = basenameFallbackPatterns(referencedPatterns, exactReferenced, [
+            ...workspace.registration.roots.gfx,
+            ...workspace.registration.roots.interface,
+            'fonts',
+        ]);
         const fallbackReferenced = fallbackPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -1070,7 +1112,11 @@ export class ScriptedGuiStudio {
                 ...(signal === undefined ? {} : { signal }),
             });
         signal?.throwIfAborted();
-        const fontPageFallbackPatterns = basenameFallbackPatterns(fontPagePatterns, exactFontPages);
+        const fontPageFallbackPatterns = basenameFallbackPatterns(fontPagePatterns, exactFontPages, [
+            ...workspace.registration.roots.gfx,
+            ...workspace.registration.roots.interface,
+            'fonts',
+        ]);
         const fallbackFontPages = fontPageFallbackPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -1079,7 +1125,26 @@ export class ScriptedGuiStudio {
             });
         const fontPages = mergeScannedFiles(exactFontPages, fallbackFontPages);
         signal?.throwIfAborted();
-        const files = mergeScannedFiles(definitions.files, referenced, fontPages);
+        const windowElements = selectedElements(definitions.graph, windowName, additionalTemplateNames);
+        const selectedPaths = new Set(windowElements.map(({ sourcePath }) => sourcePath));
+        const namedSprites = new Set(additionalSpriteNames);
+        const namedFonts = new Set();
+        for (const element of windowElements) {
+            collectNamedAttributes(element.attributes, new Set(['spriteType', 'quadTextureSprite']), namedSprites);
+            collectNamedAttributes(element.attributes, new Set(['font', 'buttonFont']), namedFonts);
+        }
+        const assetPaths = new Set(referencedPatterns.map((value) => value.toLowerCase()));
+        for (const sprite of definitions.graph.sprites)
+            if (namedSprites.has(sprite.name) ||
+                [sprite.texturePath, sprite.texturePath2, sprite.effectFile].some((value) => value !== undefined &&
+                    referenceVariants(value).some((variant) => assetPaths.has(variant.toLowerCase()))))
+                selectedPaths.add(sprite.sourcePath);
+        for (const font of definitions.graph.fonts)
+            if (namedFonts.has(font.name) ||
+                font.assetPaths.some((value) => referenceVariants(value).some((variant) => assetPaths.has(variant.toLowerCase()))))
+                selectedPaths.add(font.sourcePath);
+        const files = mergeScannedFiles(definitions.files.filter((file) => !/\.(?:gui|gfx)$/iu.test(file.relativePath) || selectedPaths.has(file.displayPath)), referenced, fontPages);
+        await stage('Resolving selected GUI assets');
         return this.graphForFiles(files, `window:${workspaceId}:${windowName}`, additionalLocalisationKeys);
     }
     async lint(input) {
@@ -1089,7 +1154,7 @@ export class ScriptedGuiStudio {
         const generatedOptions = input.generatedScenarios === undefined
             ? undefined
             : parseGeneratedScenarioOptions(input.generatedScenarios);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryAssetPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryAssetPatterns([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.enabled === true), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined), input.progress);
         let builtDefinitions;
         const evaluationDefinitions = () => (builtDefinitions ??= ClausewitzEvaluationDefinitions.build(scanned));
         const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
@@ -1108,6 +1173,7 @@ export class ScriptedGuiStudio {
         assertUniqueScenarioIds([scenario, ...relatedScenarios]);
         const budget = new RenderBudget();
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
+        await renderStage(input, 'Laying out GUI and decoding visible assets');
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
         const relatedScenes = [];
         for (const related of relatedScenarios) {
@@ -1179,7 +1245,7 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ]), scenarioLocalisationKeys([
+        ], generatedOptions?.enabled === true), scenarioLocalisationKeys([
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
@@ -1187,7 +1253,7 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ].some(({ tooltip }) => tooltip !== undefined));
+        ].some(({ tooltip }) => tooltip !== undefined), input.progress);
         let builtDefinitions;
         const evaluationDefinitions = () => (builtDefinitions ??= ClausewitzEvaluationDefinitions.build(scanned));
         const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
@@ -1207,7 +1273,9 @@ export class ScriptedGuiStudio {
         const baselineScenario = requestedBaselineScenario ??
             parsePreviewScenario({ ...scenario, id: `${scenario.id}-comparison`, state: 'normal' });
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
+        await renderStage(input, 'Laying out GUI and decoding visible assets');
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
+        await renderStage(input, 'Rasterizing GUI views');
         const render = await renderGuiScene(scene, undefined, input.signal, budget);
         const fullRenderCache = new Map([
             [visualSceneKey(scene), fullImage(render)],
@@ -1319,6 +1387,7 @@ export class ScriptedGuiStudio {
         validation.diagnostics.push(...stateValidation.diagnostics, ...resolutionValidation.diagnostics);
         validation.checks.push(...stateValidation.checks, ...resolutionValidation.checks);
         const completeValidation = withGraphDiagnostics(validationGraph, validation);
+        await renderStage(input, 'Writing GUI galleries and evidence');
         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);

package/dist/hoi4_agent_tools/gui/tool-operations.js

@@ -120,11 +120,14 @@ export async function inspectGui(engine, studio, input, context) {
             const linted = await studio.lint({
                 workspaceId: context.workspaceId,
                 windowName: input.windowName,
+                progress: (phase) => context.progress(1, 3, phase),
                 scenario: input.scenario,
                 ...(input.relatedScenarios === undefined
                     ? {}
                     : { relatedScenarios: input.relatedScenarios }),
-                generatedScenarios: input.generatedScenarios ?? {},
+                ...(input.generatedScenarios === undefined
+                    ? {}
+                    : { generatedScenarios: input.generatedScenarios }),
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 ...(context.signal === undefined ? {} : { signal: context.signal }),
             });
@@ -217,6 +220,7 @@ export async function inspectGui(engine, studio, input, context) {
 export async function renderGui(studio, input, context) {
     await context.progress(0, 4, 'Building GUI source graph');
     const rendered = await studio.renderAndStore({
+        progress: (phase) => context.progress(1, 4, phase),
         workspaceId: context.workspaceId,
         windowName: input.windowName,
         scenario: input.scenario,
@@ -231,7 +235,9 @@ export async function renderGui(studio, input, context) {
                 })),
             }),
         ...(input.relatedScenarios === undefined ? {} : { relatedScenarios: input.relatedScenarios }),
-        generatedScenarios: input.generatedScenarios ?? {},
+        ...(input.generatedScenarios === undefined
+            ? {}
+            : { generatedScenarios: input.generatedScenarios }),
         ...(input.comparisonScenario === undefined
             ? {}
             : { comparisonScenario: input.comparisonScenario }),

package/dist/hoi4_agent_tools/mcp/server/create-modern-operations.js

@@ -17,7 +17,7 @@ import { referenceTools } from '../tools/reference.js';
 import { isReferenceTool, ReferenceToolService } from '../../reference/operations.js';
 import { ModernTaskAdapter, TASKS_EXTENSION } from './modern-tasks.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
-import { modernProgressReporter, withProgressHeartbeat } from './progress.js';
+import { jobProgressReporter, modernProgressReporter, withProgressHeartbeat } from './progress.js';
 import { taskToolCatalog } from './task-tool-catalog.js';
 const rootsResponseSchema = z
     .object({
@@ -187,6 +187,7 @@ export function createModernOperationServer(engine, context = {}, tasks = new Op
             const progress = modernProgressReporter(extra);
             const result = await withProgressHeartbeat(async () => {
                 const completed = await adapter.call({ name: definition.name, arguments: arguments_ }, capabilities, operationContext, {
+                    progress: jobProgressReporter(progress),
                     requestId: extra.mcpReq.id,
                     signal: extra.mcpReq.signal,
                     ...(extra.sessionId === undefined ? {} : { sessionId: extra.sessionId }),

package/dist/hoi4_agent_tools/mcp/server/job-task-store.js

@@ -2,7 +2,7 @@ import { CallToolResultSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { jobTaskTiming } from '../../core/job-store.js';
 import { OperationTaskService, operationTaskCallSchema, operationTaskId, operationTaskMessage, operationTaskStatus, } from '../../core/operation-tasks.js';
 import { ServiceError } from '../../core/result.js';
-import { currentTaskRequestSignal } from './task-request-context.js';
+import { currentTaskRequestSignal, currentTaskRequestProgress } from './task-request-context.js';
 function legacyTask(record) {
     if (record.request.protocolTask === undefined)
         throw new ServiceError('TASK_NOT_FOUND', 'The requested protocol task does not exist');
@@ -44,6 +44,8 @@ export class PersistentJobTaskStore {
     }
     async getTask(value, _sessionId) {
         const record = await this.tasks.get(value, this.context());
+        if (record?.progress !== undefined)
+            await currentTaskRequestProgress()?.(record.progress.completed, record.progress.total ?? 1, record.progress.message);
         return record === null ? null : legacyTask(record);
     }
     async storeTaskResult(value, status, result, _sessionId) {

package/dist/hoi4_agent_tools/mcp/server/modern-tasks.js

@@ -112,6 +112,8 @@ export class ModernTaskAdapter {
             options.signal?.throwIfAborted();
             await delay(100, undefined, { signal: options.signal });
             latest = await this.known(taskId, context);
+            if (latest.progress !== undefined)
+                await options.progress?.(latest.progress.completed, latest.progress.total ?? 1, latest.progress.message);
         }
         return modernToolResult(latest, await this.tasks.result(operationTaskId(record), context));
     }

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

@@ -101,3 +101,15 @@ export async function withProgressHeartbeat(operation, reporter, message, interv
         heartbeatOwners.delete(reporter);
     }
 }
+/** Reserve the outer request's final two steps for retrieval/completion while forwarding worker phases. */
+export function jobProgressReporter(reporter) {
+    let previous;
+    return async (completed, total, message) => {
+        const identity = JSON.stringify([completed, total, message]);
+        if (identity === previous)
+            return;
+        previous = identity;
+        await reporter.report(Math.min(1, completed / Math.max(1, total)), 3, message);
+        await reporter.pulse(message);
+    };
+}

package/dist/hoi4_agent_tools/mcp/server/request-lifecycle.js

@@ -5,7 +5,7 @@ import { referenceTools } from '../tools/reference.js';
 import { jobControlTools } from '../tools/job.js';
 import { invalidArgumentsResult } from './argument-errors.js';
 import { taskToolCatalog } from './task-tool-catalog.js';
-import { progressReporter, withProgressHeartbeat } from './progress.js';
+import { jobProgressReporter, progressReporter, withProgressHeartbeat } from './progress.js';
 import { withTaskRequestSignal } from './task-request-context.js';
 import { slimToolList } from './tool-listing.js';
 // Durable task compatibility and cancellation are control traffic. They must
@@ -42,7 +42,7 @@ export function installRequestLifecycle(server, engine) {
                 return handler(request, extra);
             if (taskCall.success && backgroundTools.has(taskCall.data.params.name)) {
                 return withProgressHeartbeat(async () => {
-                    const result = await withTaskRequestSignal(extra.signal, () => handler(request, extra));
+                    const result = await withTaskRequestSignal(extra.signal, () => handler(request, extra), jobProgressReporter(progress));
                     if (taskCall.data.params.task === undefined) {
                         await progress.report(2, 3, 'Retrieving persistent operation result');
                         await progress.report(3, 3, 'Persistent operation complete');

package/dist/hoi4_agent_tools/mcp/server/task-request-context.js

@@ -1,9 +1,12 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 const taskRequestContext = new AsyncLocalStorage();
 /** Bind transport cancellation to foreground-compatible task creation only. */
-export function withTaskRequestSignal(signal, action) {
-    return taskRequestContext.run({ signal }, action);
+export function withTaskRequestSignal(signal, action, progress) {
+    return taskRequestContext.run({ signal, ...(progress === undefined ? {} : { progress }) }, action);
 }
 export function currentTaskRequestSignal() {
     return taskRequestContext.getStore()?.signal;
 }
+export function currentTaskRequestProgress() {
+    return taskRequestContext.getStore()?.progress;
+}

package/dist/hoi4_agent_tools/technology/job-operations.js

@@ -22,6 +22,7 @@ export function registerTechnologyJobs(operations, engine) {
                     workspaceId: context.workspaceId,
                     ...(context.principal === undefined ? {} : { principal: context.principal }),
                     signal: context.signal,
+                    progress: (phase) => context.progress({ completed: 1, total: 3, message: phase }),
                 });
                 await context.progress({
                     completed: 3,