hoi4-agent-tools 3.2.0 → 3.4.0

package/dist/hoi4_agent_tools/gui/studio.js

@@ -26,6 +26,7 @@ import { buildGuiSourceGraph } from './source-graph.js';
 import { assertGuiSourcePatchesSafe } from './source-patch.js';
 import { validateGuiScene, validateResolutionDrift, validateStateMatrix } from './validators.js';
 const staticGuiDefinitionPatterns = [
+    'common/focus_inlay_windows/**/*.txt',
     'common/scripted_triggers/**/*.txt',
     'common/script_constants/**/*.txt',
     'common/scripted_localisation/**/*.txt',
@@ -248,8 +249,14 @@ function basenameFallbackPatterns(exactPaths, exactFiles) {
             .map((candidate) => `**/${path.posix.basename(candidate)}`)),
     ].sort((left, right) => compareCodeUnits(left, right));
 }
-function selectedElements(graph, windowName) {
+function selectedElements(graph, windowName, additionalTemplateNames = []) {
     const byId = new Map(graph.elements.map((element) => [element.id, element]));
+    const byName = new Map();
+    for (const element of graph.elements) {
+        const definitions = byName.get(element.name) ?? [];
+        definitions.push(element);
+        byName.set(element.name, definitions);
+    }
     const relatedScriptedGuiNames = new Set(graph.scriptedGuis
         .filter((definition) => definition.windowName === windowName || definition.parentWindowName === windowName)
         .map(({ name }) => name));
@@ -265,7 +272,7 @@ function selectedElements(graph, windowName) {
             addedRelatedScriptedGui = true;
         }
     }
-    const selectedRootNames = new Set([windowName]);
+    const selectedRootNames = new Set([windowName, ...additionalTemplateNames]);
     for (const scripted of graph.scriptedGuis.filter(({ name }) => relatedScriptedGuiNames.has(name))) {
         if (scripted.windowName !== undefined)
             selectedRootNames.add(scripted.windowName);
@@ -289,6 +296,11 @@ function selectedElements(graph, windowName) {
             continue;
         selected.set(id, element);
         pending.push(...element.childIds);
+        const referenced = new Set();
+        collectNamedAttributes(element.attributes, new Set(['verticalScrollbar', 'horizontalScrollbar', 'scrollbarType', 'scrollbartype']), referenced);
+        for (const name of referenced)
+            for (const candidate of byName.get(name) ?? [])
+                pending.push(candidate.id);
     }
     return [...selected.values()];
 }
@@ -331,14 +343,14 @@ function localisationIconSpriteCandidates(token) {
     const normalized = token.startsWith('GFX_') ? token : `GFX_${token}`;
     return [...new Set([normalized, `${normalized}_texticon`, `${normalized}_text_icon`])];
 }
-export function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = [], languages = ['l_english']) {
+export function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = [], languages = ['l_english'], additionalTemplateNames = []) {
     const spriteNames = new Set(additionalSpriteNames);
     const fontNames = new Set();
     const textValues = new Set();
-    for (const element of selectedElements(graph, windowName)) {
+    for (const element of selectedElements(graph, windowName, additionalTemplateNames)) {
         collectNamedAttributes(element.attributes, new Set(['spriteType', 'quadTextureSprite']), spriteNames);
         collectNamedAttributes(element.attributes, new Set(['font', 'buttonFont']), fontNames);
-        collectNamedAttributes(element.attributes, new Set(['text', 'buttonText']), textValues);
+        collectNamedAttributes(element.attributes, new Set(['text', 'buttonText', 'context_aware_text']), textValues);
     }
     for (const localisation of graph.localisation) {
         if (textValues.has(localisation.key))
@@ -391,6 +403,10 @@ export function referencedAssetPatternsForWindow(graph, windowName, additionalSp
         const match = /^\[([^\]]+)\]$/u.exec(image);
         return match?.[1] === undefined ? [] : [match[1]];
     }));
+    for (const gui of graph.scriptedGuis.filter(({ name }) => relatedScriptedGuiNames.has(name)))
+        for (const image of gui.imageDefinitions ?? [])
+            for (const choice of image.choices)
+                spriteNames.add(choice.spriteName);
     const usesCountryFlags = graph.scriptedGuis
         .filter(({ name }) => relatedScriptedGuiNames.has(name))
         .flatMap(({ propertyDefinitions }) => propertyDefinitions)
@@ -434,7 +450,7 @@ export function referencedAssetPatternsForWindow(graph, windowName, additionalSp
                     normalizedLanguages.has(normalized.replace(/^l_/u, '')));
             })));
     const references = [
-        ...[...selectedSprites.values()].flatMap(({ texturePath, texturePath2 }) => [texturePath, texturePath2].filter((value) => value !== undefined)),
+        ...[...selectedSprites.values()].flatMap(({ texturePath, texturePath2, effectFile }) => [texturePath, texturePath2, effectFile, effectFile?.replace(/\.lua$/iu, '.shader')].filter((value) => value !== undefined)),
         ...selectedFonts.flatMap(({ assetPaths }) => assetPaths),
         ...selectedManifests.flatMap((manifest) => [
             manifest.sheet.path,
@@ -477,6 +493,35 @@ function scenarioSpriteNames(scenarios, additionalText = []) {
     }
     return [...sprites].sort((left, right) => compareCodeUnits(left, right));
 }
+function scenarioTemplateNames(scenarios) {
+    return [
+        ...new Set(scenarios.flatMap(({ lists }) => Object.values(lists).flatMap((rows) => rows.flatMap(({ entryContainer }) => typeof entryContainer === 'string' && entryContainer.length > 0 ? [entryContainer] : [])))),
+    ].sort(compareCodeUnits);
+}
+/** Native row bindings admit only bounded country tokens, never caller-supplied paths or globs. */
+export function scenarioCountryFlagPatterns(scenarios) {
+    const tags = new Set();
+    for (const scenario of scenarios) {
+        for (const values of [
+            scenario.values,
+            scenario.scriptedGui,
+            ...Object.values(scenario.lists).flat(),
+        ]) {
+            for (const [key, value] of Object.entries(values)) {
+                if (key.endsWith('.countryTag') &&
+                    typeof value === 'string' &&
+                    /^[A-Za-z0-9_]{2,64}$/u.test(value))
+                    tags.add(value.toUpperCase());
+            }
+        }
+    }
+    return [...tags]
+        .sort(compareCodeUnits)
+        .flatMap((tag) => ['', 'medium/', 'small/'].flatMap((directory) => [
+        `gfx/flags/${directory}${tag}.{bmp,dds,png,tga}`,
+        `gfx/flags/${directory}${tag}_*.{bmp,dds,png,tga}`,
+    ]));
+}
 function bmFontPagePatterns(files) {
     const references = files.flatMap((file) => {
         if (!file.relativePath.toLowerCase().endsWith('.fnt') || file.shadowedBy !== undefined)
@@ -556,21 +601,130 @@ function assertUniqueScenarioIds(scenarios) {
         seen.add(scenario.id);
     }
 }
-function scenarioMatrixEvidence(scenes) {
+function scenarioMatrixEvidence(graph, scenes) {
     const primary = scenes[0];
     if (primary === undefined)
         return { offline: true, scenarios: [], changes: [] };
+    const visibilityNames = new Set();
+    const enabledNames = new Set();
+    for (const scripted of graph.scriptedGuis) {
+        for (const trigger of scripted.triggerDefinitions) {
+            if (trigger.name.endsWith('_visible'))
+                visibilityNames.add(trigger.elementName);
+            if (trigger.name.endsWith('_click_enabled'))
+                enabledNames.add(trigger.elementName);
+        }
+        for (const property of scripted.propertyDefinitions) {
+            if (Object.keys(property.attributes).some((name) => name.toLowerCase() === 'visible'))
+                visibilityNames.add(property.elementName);
+            if (Object.keys(property.attributes).some((name) => name.toLowerCase() === 'enabled'))
+                enabledNames.add(property.elementName);
+        }
+    }
+    for (const scene of scenes) {
+        for (const name of Object.keys(scene.scenario.visibility))
+            visibilityNames.add(name);
+        for (const name of [
+            ...Object.keys(scene.scenario.values),
+            ...Object.keys(scene.scenario.scriptedGui),
+        ]) {
+            if (name.endsWith('.visible'))
+                visibilityNames.add(name.slice(0, -'.visible'.length));
+            if (name.endsWith('.enabled'))
+                enabledNames.add(name.slice(0, -'.enabled'.length));
+        }
+    }
+    const branchCoverage = [...new Set([...visibilityNames, ...enabledNames])]
+        .sort(compareCodeUnits)
+        .flatMap((name) => {
+        const matches = scenes
+            .map((scene) => ({
+            scene,
+            elements: scene.elements.filter((element) => element.name === name),
+        }))
+            .filter(({ elements }) => elements.length > 0);
+        if (matches.length === 0)
+            return [];
+        const shown = matches
+            .filter(({ elements }) => elements.some(({ visible }) => visible))
+            .map(({ scene }) => scene.scenario.id);
+        const hidden = matches
+            .filter(({ elements }) => elements.every(({ visible }) => !visible))
+            .map(({ scene }) => scene.scenario.id);
+        const enabled = matches
+            .filter(({ elements }) => elements.some(({ clickable }) => clickable))
+            .map(({ scene }) => scene.scenario.id);
+        const disabled = matches
+            .filter(({ elements }) => elements.every(({ clickable }) => !clickable))
+            .map(({ scene }) => scene.scenario.id);
+        return [
+            {
+                element: name,
+                sourcePaths: [
+                    ...new Set(matches.flatMap(({ elements }) => elements.map(({ sourcePath }) => sourcePath))),
+                ].sort(compareCodeUnits),
+                ...(visibilityNames.has(name)
+                    ? { visibility: { shown, hidden, covered: shown.length > 0 && hidden.length > 0 } }
+                    : {}),
+                ...(enabledNames.has(name)
+                    ? { enabled: { enabled, disabled, covered: enabled.length > 0 && disabled.length > 0 } }
+                    : {}),
+            },
+        ];
+    });
     const elementKey = (element) => `${element.sourceId}#${element.rowIndex ?? 0}`;
     const primaryByKey = new Map(primary.elements.map((element) => [elementKey(element), element]));
     return {
         offline: true,
+        branchCoverage,
+        branchCoverageSummary: {
+            elements: branchCoverage.length,
+            uncoveredVisibility: branchCoverage.filter((entry) => 'visibility' in entry && !entry.visibility.covered).length,
+            uncoveredEnabled: branchCoverage.filter((entry) => 'enabled' in entry && !entry.enabled.covered).length,
+        },
         scenarios: scenes.map((scene) => ({
             scenario: scene.scenario,
             sourceRevision: scene.sourceRevision,
             fidelity: scene.fidelity,
+            labelMeasurements: scene.elements
+                .filter(({ visible, text }) => visible && text !== undefined)
+                .map(({ id, name, sourcePath, rect, unclippedRect, text }) => ({
+                id,
+                name,
+                sourcePath,
+                box: rect,
+                unclippedBox: unclippedRect,
+                measuredText: {
+                    width: text.measuredWidth,
+                    height: text.measuredHeight,
+                    metricSource: text.metricSource,
+                    overflowX: text.overflowX,
+                    overflowY: text.overflowY,
+                },
+            })),
+            backgroundMeasurements: scene.elements
+                .filter(({ visible, sprite, secondarySprite, elementType }) => visible &&
+                (sprite !== undefined || secondarySprite !== undefined) &&
+                /(?:containerwindow|windowtype|buttontype|icontype|progressbar)/iu.test(elementType))
+                .map(({ id, name, parentId, sourcePath, rect, unclippedRect, sprite, secondarySprite }) => ({
+                id,
+                name,
+                parentId,
+                sourcePath,
+                box: rect,
+                unclippedBox: unclippedRect,
+                sprite: sprite?.spriteName ?? secondarySprite?.spriteName,
+                texture: sprite?.texturePath ?? secondarySprite?.texturePath,
+            })),
             visibleElements: scene.elements
                 .filter(({ visible }) => visible)
                 .map(({ id, name }) => ({ id, name })),
+            hiddenElements: scene.elements
+                .filter(({ visible }) => !visible)
+                .map(({ id, name, visibilityReason }) => ({ id, name, reason: visibilityReason })),
+            disabledElements: scene.elements
+                .filter(({ disabledReason }) => disabledReason !== undefined)
+                .map(({ id, name, disabledReason }) => ({ id, name, reason: disabledReason })),
         })),
         changes: scenes.slice(1).map((scene) => {
             const currentByKey = new Map(scene.elements.map((element) => [elementKey(element), element]));
@@ -581,6 +735,8 @@ function scenarioMatrixEvidence(scenes) {
             const resized = [];
             const textChanged = [];
             const frameChanged = [];
+            const disabled = [];
+            const enabled = [];
             for (const key of keys) {
                 const before = primaryByKey.get(key);
                 const after = currentByKey.get(key);
@@ -588,6 +744,10 @@ function scenarioMatrixEvidence(scenes) {
                     shown.push(after.name);
                 if (before?.visible === true && after?.visible !== true)
                     hidden.push(before.name);
+                if (before?.clickable === true && after?.clickable === false)
+                    disabled.push(after.name);
+                if (before?.clickable === false && after?.clickable === true)
+                    enabled.push(after.name);
                 if (before === undefined || after === undefined)
                     continue;
                 if (before.unclippedRect.x !== after.unclippedRect.x ||
@@ -609,6 +769,8 @@ function scenarioMatrixEvidence(scenes) {
                 resized,
                 textChanged,
                 frameChanged,
+                disabled,
+                enabled,
             };
         }),
     };
@@ -744,7 +906,7 @@ export class ScriptedGuiStudio {
         const files = mergeScannedFiles(snapshot.files, localisationFiles);
         return this.graphForFiles(files, `workspace:${workspaceId}`);
     }
-    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = []) {
+    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = []) {
         const workspace = this.resolver.get(workspaceId, principal);
         const layoutPatterns = guiLayoutPatterns(workspace);
         const overlayLayouts = await this.engine.scan(workspaceId, {
@@ -753,12 +915,15 @@ export class ScriptedGuiStudio {
         }, principal, signal);
         let layoutFiles = overlayLayouts.files;
         let layoutGraph = this.graphForFiles(layoutFiles, `layout:${workspaceId}`).graph;
-        if (!layoutGraph.elements.some(({ name }) => name === windowName)) {
+        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));
+        if ([...requiredNames].some((name) => !availableNames.has(name))) {
             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));
+            const selectedPaths = new Set(selectedElements(gameGraph, windowName, [...requiredNames]).map(({ sourcePath }) => sourcePath));
             layoutFiles = mergeScannedFiles(layoutFiles, gameLayouts.files.filter(({ displayPath }) => selectedPaths.has(displayPath)));
             layoutGraph = this.graphForFiles(layoutFiles, `layout:${workspaceId}`).graph;
         }
@@ -771,7 +936,10 @@ export class ScriptedGuiStudio {
         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, languages);
+        const referencedPatterns = [
+            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames),
+            ...additionalAssetPatterns,
+        ];
         const exactReferenced = referencedPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -814,7 +982,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));
+        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]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
@@ -844,7 +1012,7 @@ 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], scenarioSpriteNames([beforeScenario, afterScenario]));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryFlagPatterns([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);
@@ -893,7 +1061,15 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ], generatedOptions?.textSamples));
+        ], generatedOptions?.textSamples), scenarioTemplateNames([
+            placeholderScenario,
+            ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
+            ...explicitRelatedScenarios,
+        ]), scenarioCountryFlagPatterns([
+            placeholderScenario,
+            ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
+            ...explicitRelatedScenarios,
+        ]));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
@@ -979,6 +1155,35 @@ export class ScriptedGuiStudio {
         const baselineScene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, baselineScenario, catalog);
         const baselineImage = await renderFull(baselineScene);
         const comparison = await compareGuiImages(baselineImage.png, fullImage(render).png, budget, input.signal);
+        let sourceBaselineScene;
+        let sourceBaselineImage;
+        let sourceComparison;
+        if (input.sourceBaseline !== undefined) {
+            const { relativePath, source } = input.sourceBaseline;
+            guiTextPackageFileKind(workspace, relativePath, true);
+            const original = scanned.files.find((file) => file.rootKind === 'mod' &&
+                portableSourcePathKey(file.relativePath) === portableSourcePathKey(relativePath));
+            if (original === undefined)
+                throw new ServiceError('GUI_SOURCE_BASELINE_FILE_MISSING', 'Source baseline must identify a scanned mod-owned GUI file', { relativePath });
+            const bytes = Buffer.from(source, 'utf8');
+            if (bytes.length > SOURCE_MAX_BYTES)
+                throw new ServiceError('GUI_SOURCE_BASELINE_TOO_LARGE', 'Source baseline exceeds the file byte limit');
+            const baselineFiles = overlayGuiTextPackageFiles(scanned.files, [
+                {
+                    relativePath,
+                    kind: 'gui',
+                    bytes,
+                    absolutePath: original.absolutePath,
+                    loadOrder: original.loadOrder,
+                },
+            ]);
+            const baselineGraph = this.graphForFiles(baselineFiles, `source-baseline:${input.workspaceId}`).graph;
+            if (!baselineGraph.elements.some(({ name }) => name === input.windowName))
+                throw new ServiceError('GUI_SOURCE_BASELINE_WINDOW_MISSING', 'Source baseline does not define the requested GUI window', { relativePath, windowName: input.windowName });
+            sourceBaselineScene = await buildGuiScene(baselineGraph, baselineFiles, input.windowName, scenario, new GuiAssetCatalog(baselineGraph, baselineFiles, budget, scenario.language));
+            sourceBaselineImage = await renderFull(sourceBaselineScene);
+            sourceComparison = await compareGuiImages(sourceBaselineImage.png, fullImage(render).png, budget, input.signal);
+        }
         const renderedSourceIds = [
             ...scenarioScenes,
             ...stateScenes,
@@ -1048,7 +1253,7 @@ export class ScriptedGuiStudio {
         add(`${slug}-validation.json`, 'application/json', `${canonicalJson(completeValidation)}\n`, 'gui-validation-report', [...scenarioScenes, ...stateScenes, ...resolutionScenes]);
         add(`${slug}-scenario-matrix.svg`, 'image/svg+xml', scenarioGallerySvg, 'gui-scripted-scenario-matrix', scenarioScenes);
         add(`${slug}-scenario-matrix.png`, 'image/png', scenarioGalleryPng, 'gui-scripted-scenario-matrix', scenarioScenes);
-        add(`${slug}-scenario-matrix.json`, 'application/json', `${canonicalJson(scenarioMatrixEvidence(scenarioScenes))}\n`, 'gui-scripted-scenario-matrix-json', scenarioScenes);
+        add(`${slug}-scenario-matrix.json`, 'application/json', `${canonicalJson(scenarioMatrixEvidence(scanned.graph, scenarioScenes))}\n`, 'gui-scripted-scenario-matrix-json', scenarioScenes);
         add(`${slug}-state-matrix.svg`, 'image/svg+xml', stateGallerySvg, 'gui-state-matrix', stateScenes);
         add(`${slug}-state-matrix.png`, 'image/png', stateGalleryPng, 'gui-state-matrix', stateScenes);
         add(`${slug}-state-matrix.json`, 'application/json', `${canonicalJson({ offline: true, scenarios: stateScenes.map(({ scenario: stateScenario, fidelity }) => ({ scenario: stateScenario, fidelity })) })}\n`, 'gui-state-matrix-json', stateScenes);
@@ -1060,6 +1265,23 @@ export class ScriptedGuiStudio {
             baselineScene,
         ]);
         add(`${slug}-comparison.json`, 'application/json', comparison.json, 'gui-before-after-comparison', [scene, baselineScene]);
+        if (sourceBaselineScene !== undefined &&
+            sourceBaselineImage !== undefined &&
+            sourceComparison !== undefined) {
+            add(`${slug}-source-baseline.png`, 'image/png', sourceBaselineImage.png, 'gui-source-baseline', [sourceBaselineScene]);
+            add(`${slug}-source-comparison.png`, 'image/png', sourceComparison.png, 'gui-source-comparison', [sourceBaselineScene, scene]);
+            add(`${slug}-source-comparison.json`, 'application/json', `${canonicalJson({
+                kind: 'gui-source-comparison',
+                scenario,
+                before: {
+                    sourceRevision: sourceBaselineScene.sourceRevision,
+                    sourcePath: input.sourceBaseline.relativePath,
+                    sourceHash: sha256Bytes(Buffer.from(input.sourceBaseline.source, 'utf8')),
+                },
+                after: { sourceRevision: scene.sourceRevision },
+                comparison: JSON.parse(sourceComparison.json),
+            })}\n`, 'gui-source-comparison', [sourceBaselineScene, scene]);
+        }
         const stored = await this.artifacts.withAtomicChunkedWrites(workspace, writes, (artifacts) => Promise.resolve([...artifacts]), input.signal);
         return {
             artifacts: stored,
@@ -1069,6 +1291,7 @@ export class ScriptedGuiStudio {
             stateScenes,
             resolutionScenes,
             comparison,
+            ...(sourceComparison === undefined ? {} : { sourceComparison }),
             validation: completeValidation,
         };
     }
@@ -1193,7 +1416,7 @@ export class ScriptedGuiStudio {
         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, [previewScenario.language], scenarioSpriteNames([previewScenario]));
+            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryFlagPatterns([previewScenario]));
         const exactTargets = await this.scanner.scan(workspace, {
             patterns: prepared.map(({ relativePath }) => relativePath),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
@@ -1213,7 +1436,10 @@ export class ScriptedGuiStudio {
             const scenario = parsePreviewScenario(input.scenario);
             const renderBudget = new RenderBudget();
             let proposedGraph = buildGuiSourceGraph(proposedFiles, this.engine.indexFiles(proposedFiles));
-            const proposedAssetPatterns = referencedAssetPatternsForWindow(proposedGraph, input.windowName, [], [scenario.language]);
+            const proposedAssetPatterns = [
+                ...referencedAssetPatternsForWindow(proposedGraph, input.windowName, [], [scenario.language], scenarioTemplateNames([scenario])),
+                ...scenarioCountryFlagPatterns([scenario]),
+            ];
             const exactProposedAssets = proposedAssetPatterns.length === 0
                 ? []
                 : await this.scanner.scan(workspace, {

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

@@ -235,6 +235,7 @@ export async function renderGui(studio, input, context) {
         ...(input.comparisonScenario === undefined
             ? {}
             : { comparisonScenario: input.comparisonScenario }),
+        ...(input.sourceBaseline === undefined ? {} : { sourceBaseline: input.sourceBaseline }),
         ...(context.principal === undefined ? {} : { principal: context.principal }),
         ...(context.signal === undefined ? {} : { signal: context.signal }),
     });
@@ -257,6 +258,14 @@ export async function renderGui(studio, input, context) {
             changedPixels: rendered.comparison.changedPixels,
             changedRatio: rendered.comparison.changedRatio,
         },
+        ...(rendered.sourceComparison === undefined
+            ? {}
+            : {
+                sourceComparison: {
+                    changedPixels: rendered.sourceComparison.changedPixels,
+                    changedRatio: rendered.sourceComparison.changedRatio,
+                },
+            }),
         fidelityCounts: Object.fromEntries(Object.entries(rendered.render.fidelity).map(([key, values]) => [key, values.length])),
         offlineRepresentation: true,
     });

package/dist/hoi4_agent_tools/gui/validators.js

@@ -207,6 +207,36 @@ function validateScenarioExpectations(scene, diagnostics) {
 function validateButtonLabelsAndBackgrounds(scene, diagnostics) {
     const visible = scene.elements.filter((element) => element.visible);
     const byId = new Map(scene.elements.map((element) => [element.id, element]));
+    const backgrounds = new Map();
+    for (const element of visible) {
+        if (element.elementType !== 'background' ||
+            element.parentId === undefined ||
+            area(element.rect) === 0)
+            continue;
+        const previous = backgrounds.get(element.parentId);
+        const rect = element.unclippedRect;
+        const x = Math.min(previous?.x ?? rect.x, rect.x);
+        const y = Math.min(previous?.y ?? rect.y, rect.y);
+        backgrounds.set(element.parentId, {
+            x,
+            y,
+            width: Math.max(previous === undefined ? x : previous.x + previous.width, rect.x + rect.width) - x,
+            height: Math.max(previous === undefined ? y : previous.y + previous.height, rect.y + rect.height) -
+                y,
+        });
+    }
+    const backgroundOwner = (element) => {
+        const visited = new Set();
+        let parent = element.parentId === undefined ? undefined : byId.get(element.parentId);
+        while (parent !== undefined && !visited.has(parent.id)) {
+            visited.add(parent.id);
+            const rect = parent.sprite === undefined ? backgrounds.get(parent.id) : parent.unclippedRect;
+            if (rect !== undefined)
+                return { owner: parent, rect };
+            parent = parent.parentId === undefined ? undefined : byId.get(parent.parentId);
+        }
+        return undefined;
+    };
     const buttons = visible.filter((element) => element.clickable && /button/iu.test(element.elementType));
     const labels = visible.filter((element) => element.text !== undefined);
     const inferredButtonByLabel = new Map();
@@ -249,22 +279,18 @@ function validateButtonLabelsAndBackgrounds(scene, diagnostics) {
                     deltaY: delta.y,
                 }));
         }
-        let parent = label.parentId === undefined ? undefined : byId.get(label.parentId);
-        while (parent !== undefined && parent.sprite === undefined)
-            parent = parent.parentId === undefined ? undefined : byId.get(parent.parentId);
+        const parent = backgroundOwner(label);
         if (parent !== undefined &&
-            !contains(parent.unclippedRect, label.unclippedRect, 0.5) &&
-            intersection(parent.unclippedRect, label.unclippedRect) !== undefined)
-            diagnostics.push(issue('GUI_CONTENT_CROSSES_BACKGROUND_EDGE', 'warning', 'layout', `${label.name} crosses the visible background boundary of ${parent.name} in scenario ${scene.scenario.id}.`, label, { scenarioId: scene.scenario.id, element: label.name, background: parent.name }));
+            !contains(parent.rect, label.unclippedRect, 0.5) &&
+            intersection(parent.rect, label.unclippedRect) !== undefined)
+            diagnostics.push(issue('GUI_CONTENT_CROSSES_BACKGROUND_EDGE', 'warning', 'layout', `${label.name} crosses the visible background boundary of ${parent.owner.name} in scenario ${scene.scenario.id}.`, label, { scenarioId: scene.scenario.id, element: label.name, background: parent.owner.name }));
     }
     for (const control of visible.filter((element) => element.clickable && element.text === undefined)) {
-        let parent = control.parentId === undefined ? undefined : byId.get(control.parentId);
-        while (parent !== undefined && parent.sprite === undefined)
-            parent = parent.parentId === undefined ? undefined : byId.get(parent.parentId);
+        const parent = backgroundOwner(control);
         if (parent !== undefined &&
-            !contains(parent.unclippedRect, control.unclippedRect, 0.5) &&
-            intersection(parent.unclippedRect, control.unclippedRect) !== undefined)
-            diagnostics.push(issue('GUI_CONTENT_CROSSES_BACKGROUND_EDGE', 'warning', 'layout', `${control.name} crosses the visible background boundary of ${parent.name} in scenario ${scene.scenario.id}.`, control, { scenarioId: scene.scenario.id, element: control.name, background: parent.name }));
+            !contains(parent.rect, control.unclippedRect, 0.5) &&
+            intersection(parent.rect, control.unclippedRect) !== undefined)
+            diagnostics.push(issue('GUI_CONTENT_CROSSES_BACKGROUND_EDGE', 'warning', 'layout', `${control.name} crosses the visible background boundary of ${parent.owner.name} in scenario ${scene.scenario.id}.`, control, { scenarioId: scene.scenario.id, element: control.name, background: parent.owner.name }));
     }
 }
 function sameRect(left, right) {

package/dist/hoi4_agent_tools/map/operations.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { compareCodeUnits, deterministicId, sha256Bytes } from '../core/canonical.js';
 import { ServiceError } from '../core/result.js';
-import { applyReplacements, assignments, encodeSource, parseLocalisation, } from '../core/source/index.js';
+import { applyReplacements, assignments, encodeSource, parseLocalisation, parseClausewitz, } from '../core/source/index.js';
 import { rgbKey } from './bmp.js';
 import { MAP_MASK_CELL_LIMIT, MAP_POLYGON_WORK_LIMIT, MAP_SELECTED_OFFSET_BYTES, MAP_SELECTED_PIXEL_LIMIT, } from './limits.js';
 import { derivedStateCapital, encodeTextDocument, MapWorkspaceIndex, parseTextDocument, } from './model.js';
@@ -2718,6 +2718,72 @@ function renumberMapping(existingIds, operation) {
         ...(targetOccupied ? [[operation.toId, operation.fromId]] : []),
     ]);
 }
+const EXTERNAL_SCRIPT_REFERENCE_KEYS = {
+    province: new Set(['province', 'province_id', 'start_province', 'target_province']),
+    state: new Set([
+        'state',
+        'state_id',
+        'start_state',
+        'target_state',
+        'owns_state',
+        'controls_state',
+        'transfer_state',
+        'transfer_state_to',
+    ]),
+    'strategic-region': new Set(['strategic_region', 'strategic_region_id']),
+};
+function externalScriptFile(relativePath) {
+    return /^(?:events|common\/(?:national_focus|decisions|scripted_effects|scripted_triggers|on_actions|ideas|characters)|history\/countries)\/.+\.txt$/u.test(relativePath);
+}
+function remapExternalScriptReferences(index, changes, mapping, entity, operationId) {
+    const keys = EXTERNAL_SCRIPT_REFERENCE_KEYS[entity];
+    for (const file of index.sourceFiles) {
+        if (file.shadowedBy !== undefined || !externalScriptFile(file.relativePath))
+            continue;
+        const document = parseClausewitz(file.bytes, file.displayPath);
+        if (document.diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker'))
+            throw new ServiceError('MAP_EXTERNAL_SCRIPT_PARSE_BLOCKED', 'A selected external script cannot be safely inspected for typed map references', {
+                relativePath: file.relativePath,
+                diagnosticCodes: document.diagnostics.map(({ code }) => code),
+            });
+        const replacements = [];
+        const visit = (entry) => {
+            if (entry.type === 'block') {
+                for (const child of entry.entries)
+                    visit(child);
+                return;
+            }
+            if (entry.type !== 'assignment')
+                return;
+            if (entry.value.type === 'block') {
+                for (const child of entry.value.entries)
+                    visit(child);
+                return;
+            }
+            if (!keys.has(entry.key.value) || !/^\d+$/u.test(entry.value.value))
+                return;
+            const replacement = mapping.get(Number(entry.value.value));
+            if (replacement === undefined)
+                return;
+            if (file.rootKind !== 'mod' && file.rootKind !== 'fixture')
+                throw new ServiceError('MAP_EXTERNAL_REFERENCE_READ_ONLY', 'A typed external map reference is owned by a read-only source', {
+                    relativePath: file.relativePath,
+                    rootKind: file.rootKind,
+                    key: entry.key.value,
+                    id: entry.value.value,
+                });
+            replacements.push({
+                start: entry.value.start,
+                end: entry.value.end,
+                text: String(replacement),
+                description: `Renumber typed ${entity} reference in ${entry.key.value}`,
+            });
+        };
+        visit(document.root);
+        if (replacements.length > 0)
+            addChange(changes, file.relativePath, applyReplacements(document, replacements), operationId, 'text/plain');
+    }
+}
 function renameLocalisationKeys(index, changes, keys, operationId) {
     if (keys.size === 0)
         return;
@@ -2838,6 +2904,7 @@ function applyRenumberMapEntity(base, changes, operation) {
             commitRegion(changes, region, uniqueSorted(region.provinces.map((id) => remapProvinceId(mapping, id))), operation.id);
         }
         remapReferenceFiles(index, changes, mapping, operation.id);
+        remapExternalScriptReferences(index, changes, mapping, operation.entity, operation.id);
         if (operation.renameLocalisation ?? true) {
             const keys = new Map();
             for (const [fromId, toId] of mapping) {
@@ -2863,6 +2930,7 @@ function applyRenumberMapEntity(base, changes, operation) {
             commitState(changes, state, data, { id: true, ...(standardName ? { name: true } : {}) }, operation.id);
         }
         remapBuildingPositionStateIds(index, changes, mapping, operation.id);
+        remapExternalScriptReferences(index, changes, mapping, operation.entity, operation.id);
         if (operation.renameLocalisation ?? true)
             renameLocalisationKeys(currentIndex(base, changes), changes, localisationKeys, operation.id);
         return;
@@ -2881,6 +2949,7 @@ function applyRenumberMapEntity(base, changes, operation) {
         addChange(changes, region.file.relativePath, patchRegion(region, region.provinces, { id: toId, ...(standardName ? { name } : {}) }, false), operation.id, 'text/plain');
     }
     remapWeatherPositionRegionIds(index, changes, mapping, operation.id);
+    remapExternalScriptReferences(index, changes, mapping, operation.entity, operation.id);
     if (operation.renameLocalisation ?? true)
         renameLocalisationKeys(currentIndex(base, changes), changes, localisationKeys, operation.id);
 }