hoi4-agent-tools 4.0.3 → 4.0.4

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 4.0.4 - 2026-10-14
+
+- Preview individual GUI windows without redundant full symbol indexes, workspace-wide asset fallback or unbound country-flag inventories; reuse condition definitions across render variants.
+- Index technology sources once across layers and scope folder rendering to definitions, layouts and unlock targets. Full inspection retains inbound grants and references.
+- Report render phases and include the last phase in worker deadline errors. Existing parsing, raster-memory, canonical-path and stale-source limits remain enforced.
+- Resolve transitive localisation `$KEY$` references across files and bounded scenario substitutions; retain diagnostics for cycles and missing runtime values.
+- Honour numeric flag presence in scalar visibility checks, matching valued-flag super-event localisation conditions.
+- Preserve supplied GUI scenarios by default; exploratory `generatedScenarios` is now opt-in. Explicit state/resolution matrices and public schema shapes are unchanged.
+- Retain regression coverage for hidden sub-windows, timed animated-sprite frames, 16-bit DDS portraits, declared font colours, worker recovery and render-memory ceilings.
+
 ## 4.0.3 - 2026-10-12
 
 - Publish the README with the supplied HOI4 MCP Server thumbnail and direct links to the demo video on YouTube.

package/dist/hoi4_agent_tools/core/clausewitz-evaluation.js

@@ -31,11 +31,13 @@ export class ClausewitzEvaluationDefinitions {
     scriptedTriggers = new Map();
     localConstants = new Map();
     static build(snapshot) {
-        const cached = definitionCache.get(snapshot);
+        const cached = definitionCache.get(snapshot.files);
         if (cached !== undefined)
             return cached;
         const result = new ClausewitzEvaluationDefinitions();
-        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined && relativePath.toLowerCase().endsWith('.txt'))) {
+        for (const file of snapshot.files.filter(({ shadowedBy, relativePath, bytes }) => shadowedBy === undefined &&
+            relativePath.toLowerCase().endsWith('.txt') &&
+            bytes.includes(0x40))) {
             const document = parseClausewitz(file.bytes, file.displayPath);
             const locals = new Map();
             for (const assignment of scalarAssignments(document.root)) {
@@ -84,7 +86,7 @@ export class ClausewitzEvaluationDefinitions {
                 });
             }
         }
-        definitionCache.set(snapshot, result);
+        definitionCache.set(snapshot.files, result);
         return result;
     }
 }

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -286,7 +286,11 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             : { state: value ? 'true' : 'false', unresolved: [] };
     }
     if (key === 'has_country_flag' || key === 'has_global_flag' || key === 'has_state_flag') {
-        const explicit = bool(scopeStateValue(scenario, `flag.${right}`, scopeContext));
+        const stored = key === 'has_global_flag'
+            ? (scopeStateValue(scenario, `global_flag.${right}`, scopeContext) ??
+                scopeStateValue(scenario, `flag.${right}`, scopeContext))
+            : scopeStateValue(scenario, `flag.${right}`, scopeContext);
+        const explicit = typeof stored === 'number' && Number.isFinite(stored) ? true : bool(stored);
         if (explicit !== undefined)
             return { state: explicit ? 'true' : 'false', unresolved: [] };
         const flags = key === 'has_global_flag' && scenario.globalFlags !== undefined

package/dist/hoi4_agent_tools/core/index.js

@@ -383,6 +383,17 @@ export class SymbolIndex {
             },
         });
     }
+    /** Record parser coverage without allocating symbols for a domain that builds its own graph. */
+    recordSourceCoverage(file, diagnostics) {
+        const limits = sourcePartialLimitDiagnostics(diagnostics);
+        if (limits.length > 0) {
+            this.recordSkippedSource(file, limits);
+            return false;
+        }
+        if (isWorkspaceOwnedSource(file) && file.shadowedBy === undefined)
+            this.addDiagnostics(diagnostics);
+        return true;
+    }
     addSymbol(record) {
         if (this.symbols.length >= INDEX_RECORD_LIMIT) {
             this.#complete = false;

package/dist/hoi4_agent_tools/core/job-executor.js

@@ -106,10 +106,11 @@ export class JobExecutor {
         const controller = new AbortController();
         const watchStop = new AbortController();
         let watchFailure;
+        let lastProgressMessage = claimed.record.progress?.message;
         const deadlineTimer = options.deadlineMs === undefined || operation.mutation
             ? undefined
             : setTimeout(() => {
-                watchFailure = new ServiceError('JOB_DEADLINE_EXCEEDED', 'The job ran past its deadline and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds');
+                watchFailure = new ServiceError('JOB_DEADLINE_EXCEEDED', `The job ran past its deadline and was stopped${lastProgressMessage === undefined ? '' : ` during: ${lastProgressMessage.slice(0, 160)}`}; narrow its selector or limits, or raise jobDeadlineSeconds`);
                 controller.abort(watchFailure);
             }, Math.max(0, options.deadlineMs - Date.now()));
         const watch = (async () => {
@@ -136,6 +137,7 @@ export class JobExecutor {
             signal: controller.signal,
             checkpoint: claimed.record.checkpoint,
             progress: async (progress) => {
+                lastProgressMessage = progress.message;
                 await this.jobs.store.updateOwned(scope, id, owner.token, { progress }, controller.signal);
             },
             saveCheckpoint: async (checkpoint) => {

package/dist/hoi4_agent_tools/core/job-worker-host.js

@@ -309,7 +309,7 @@ export class JobWorkerHost {
                     await stopChild(child, this.stoppedByHost);
                     await this.jobs.failInterrupted(workspaceId, id, {
                         code: 'JOB_DEADLINE_EXCEEDED',
-                        message: `The job ran longer than ${jobDeadlineSeconds} seconds and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds`,
+                        message: `The job ran longer than ${jobDeadlineSeconds} seconds and was stopped${record.progress === undefined ? '' : ` during: ${record.progress.message.slice(0, 160)}`}; narrow its selector or limits, or raise jobDeadlineSeconds`,
                     }, principal);
                     return;
                 }

package/dist/hoi4_agent_tools/core/render-progress.js

@@ -0,0 +1,7 @@
+export async function renderStage(input, phase) {
+    input.signal?.throwIfAborted();
+    await new Promise((resolve) => setImmediate(resolve));
+    input.signal?.throwIfAborted();
+    await input.progress?.(phase);
+    input.signal?.throwIfAborted();
+}

package/dist/hoi4_agent_tools/gui/layout.js

@@ -219,15 +219,20 @@ function resolveTokenText(value, scenario, localisation, rowValues) {
         /^[A-Za-z0-9_.-]+$/u.test(value) &&
         (value.includes('_') || value === value.toUpperCase()))
         missingLocalisation = true;
-    text = replaceTextBounded(text, /\$([A-Za-z0-9_.-]+)\$/gu, (match) => {
+    const expandTokens = (input, stack, depth) => replaceTextBounded(input, /\$([A-Za-z0-9_.-]+)\$/gu, (match) => {
         const key = match[1] ?? '';
-        const replacement = scenario.localisation[key] ?? localisation.get(key);
-        if (replacement === undefined) {
-            unresolved.push(`$${key}$`);
-            return `$${key}$`;
+        const replacement = scenario.localisation[key] ??
+            localisation.get(key) ??
+            rowValues?.[key] ??
+            scenario.values[key] ??
+            scenario.variables[key];
+        if (replacement === undefined || stack.has(key) || depth >= 16) {
+            unresolved.push(match[0]);
+            return match[0];
         }
-        return replacement;
+        return expandTokens(String(replacement), new Set([...stack, key]), depth + 1);
     }, 'GUI localisation substitution');
+    text = expandTokens(text, new Set([value]), 0);
     text = replaceTextBounded(text, /\[\?([^\]|]+)(?:\|[^\]]+)?\]/gu, (match) => {
         const key = match[1] ?? '';
         const shortKey = key.slice(key.lastIndexOf('.') + 1);
@@ -2026,7 +2031,9 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     const localisation = new Map(graph.localisation
         .filter((entry) => entry.language.toLowerCase() === scenario.language.toLowerCase() ||
         entry.language.toLowerCase() === `l_${scenario.language.toLowerCase()}`)
-        .map((entry) => [entry.key, entry.value]));
+        // Graph localisation is ordered with the active (highest-priority) definition first.
+        .map((entry) => [entry.key, entry.value])
+        .reverse());
     if (localisation.size === 0) {
         for (const entry of graph.localisation)
             if (!localisation.has(entry.key))
@@ -2058,7 +2065,7 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     const countryFlagProperties = new Map();
     const conditionDefinitions = relevantScriptedGuiNames.size === 0
         ? undefined
-        : ClausewitzEvaluationDefinitions.build({ files: [...scannedFiles] });
+        : ClausewitzEvaluationDefinitions.build({ files: scannedFiles });
     const conditionScenario = guiConditionScenario(scenario);
     for (const scripted of graph.scriptedGuis.filter(({ name }) => relevantScriptedGuiNames.has(name))) {
         const source = scannedFiles.find(({ displayPath }) => displayPath === scripted.sourcePath);

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

@@ -3,7 +3,7 @@ import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.j
 import { evaluateGuiCondition, guiConditionScenario, guiConditionVariables, guiExplicitConditionValues, } from './scenario-conditions.js';
 import { parsePreviewScenario } from './scenario.js';
 const countryNames = ['Germany', 'France', 'Poland', 'Italy', 'Brazil', 'India', 'Canada'];
-const countryTags = ['GER', 'FRA', 'POL', 'ITA', 'BRA', 'RAJ', 'CAN'];
+export const generatedCountryTags = ['GER', 'FRA', 'POL', 'ITA', 'BRA', 'RAJ', 'CAN'];
 const countryIdeologies = [
     'fascism',
     'democratic',
@@ -435,7 +435,7 @@ function generatedRows(count, random, options) {
     return Array.from({ length: count }, (_unused, index) => {
         const countryIndex = (countryOffset + index) % countryNames.length;
         const name = countryNames[countryIndex];
-        const tag = countryTags[countryIndex];
+        const tag = generatedCountryTags[countryIndex];
         const ideology = countryIdeologies[countryIndex];
         const value = generatedNumber(options, random);
         return {
@@ -587,7 +587,7 @@ export function generateGuiPreviewScenarios(graph, windowName, base, options, de
         const elementStates = { ...base.elementStates };
         const scopedCountries = new Map();
         const generatedCountryIndex = random.integer(0, countryNames.length - 1);
-        const generatedCountryTag = countryTags[generatedCountryIndex];
+        const generatedCountryTag = generatedCountryTags[generatedCountryIndex];
         for (const key of tokens.numeric)
             setIfMissing(values, key, generatedNumberForKey(key, options, random, numericConstraints.ranges.get(key)));
         for (const [elementName, { minimum, maximum }] of progressRanges) {

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';
@@ -1306,7 +1307,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 +1325,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 +1406,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 +1441,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 +1464,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,24 +1016,33 @@ 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]);
@@ -1028,25 +1050,38 @@ export class ScriptedGuiStudio {
             collectNamedAttributes(element.attributes, new Set(['verticalScrollbar', 'horizontalScrollbar', 'scrollbarType', 'scrollbartype']), requiredNames);
         const availableNames = new Set(layoutGraph.elements.map(({ name }) => name));
         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 +1089,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 +1109,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 +1122,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 +1151,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 +1170,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 +1242,7 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ]), scenarioLocalisationKeys([
+        ], generatedOptions?.enabled === true), scenarioLocalisationKeys([
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
@@ -1187,7 +1250,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 +1270,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 +1384,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);