hoi4-agent-tools 3.8.1 → 3.10.0

package/dist/hoi4_agent_tools/core/source/cache.js

@@ -27,29 +27,50 @@ function decodedDocument(encoded, expected) {
         throw new Error('Persistent source document does not match its source identity');
     return value;
 }
-/** Process-local parsed facts; serialized entries cannot be mutated by their consumers. */
+/** Puts between halvings of every entry's hit count, so entries no longer read become evictable. */
+const HIT_AGING_INTERVAL = 4096;
+/** Keys of documents turned away from a full cache, remembered so a repeat can be admitted. */
+const DOORKEEPER_KEYS = 16_384;
+/**
+ * Process-local parsed facts; serialized entries cannot be mutated by their consumers.
+ *
+ * A workspace scan often parses more source than the cache holds. Plain LRU then evicts
+ * every document before its next use and pays serialization for nothing. A full cache
+ * therefore turns a document away the first time, remembering only its key, and admits it
+ * on a later miss by displacing entries that were never read; a rejected document is not
+ * serialized. Repeated scans keep what fits and hit it. Hit counts age, so documents that
+ * stop being read become evictable again.
+ */
 export class SourceDocumentCache {
     maxBytes;
     #entries = new Map();
     #bytes = 0;
+    /** Bytes held by entries without hits, which a new document may displace. */
+    #coldBytes = 0;
+    #puts = 0;
     #hits = 0;
     #misses = 0;
     #evictions = 0;
+    #rejections = 0;
+    #doorkeeper = new Set();
     constructor(maxBytes = 64 * 1024 * 1024) {
         this.maxBytes = maxBytes;
         if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
             throw new RangeError('Source cache size must be a non-negative integer');
     }
     get(key) {
-        const encoded = this.#entries.get(key);
-        if (encoded === undefined) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined) {
             this.#misses += 1;
             return undefined;
         }
         this.#hits += 1;
+        if (entry.hits === 0)
+            this.#coldBytes -= entrySize(key, entry.encoded);
+        entry.hits += 1;
         this.#entries.delete(key);
-        this.#entries.set(key, encoded);
-        return decodedDocument(encoded);
+        this.#entries.set(key, entry);
+        return decodedDocument(entry.encoded);
     }
     /** Availability check without deserialization or cache-hit accounting. */
     has(key) {
@@ -61,8 +82,19 @@ export class SourceDocumentCache {
         const estimatedBytes = document.bytes.length * 12 + document.tokens.length * 512 + key.length * 2 + 128;
         if (this.maxBytes === 0 || estimatedBytes > this.maxBytes)
             return;
-        const encoded = serialize(document);
-        this.retain(key, encoded);
+        this.#age();
+        const previous = this.#entries.get(key);
+        const reusable = previous === undefined ? 0 : entrySize(key, previous.encoded);
+        const free = this.maxBytes - this.#bytes + reusable;
+        if (estimatedBytes > free) {
+            // Only a document missed before may displace entries, and only entries never read.
+            if (!this.#doorkeeper.delete(key) || estimatedBytes > free + this.#coldBytes) {
+                this.#remember(key);
+                this.#rejections += 1;
+                return;
+            }
+        }
+        this.retain(key, serialize(document));
     }
     /** Import one authenticated same-runtime entry without counting it as a process-local hit. */
     importEncoded(key, encoded, expected) {
@@ -70,42 +102,79 @@ export class SourceDocumentCache {
         this.retain(key, Buffer.from(encoded));
     }
     exportEncoded(key) {
-        const encoded = this.#entries.get(key);
-        return encoded === undefined ? undefined : Buffer.from(encoded);
+        const entry = this.#entries.get(key);
+        return entry === undefined ? undefined : Buffer.from(entry.encoded);
     }
     retain(key, encoded) {
-        const size = encoded.length + key.length * 2 + 128;
+        const size = entrySize(key, encoded);
         if (size > this.maxBytes)
             return;
-        const previous = this.#entries.get(key);
-        if (previous !== undefined)
-            this.#bytes -= previous.length + key.length * 2 + 128;
-        this.#entries.delete(key);
-        while (this.#bytes + size > this.maxBytes) {
-            const oldest = this.#entries.entries().next().value;
-            if (oldest === undefined)
+        this.#remove(key);
+        // Displace the oldest entries that were never read again; read entries stay.
+        for (const [oldKey, entry] of this.#entries) {
+            if (this.#bytes + size <= this.maxBytes)
                 break;
-            this.#entries.delete(oldest[0]);
-            this.#bytes -= oldest[1].length + oldest[0].length * 2 + 128;
+            if (entry.hits > 0)
+                continue;
+            this.#remove(oldKey);
             this.#evictions += 1;
         }
-        this.#entries.set(key, encoded);
+        if (this.#bytes + size > this.maxBytes) {
+            this.#rejections += 1;
+            return;
+        }
+        this.#entries.set(key, { encoded, hits: 0 });
         this.#bytes += size;
+        this.#coldBytes += size;
+    }
+    #remember(key) {
+        this.#doorkeeper.delete(key);
+        this.#doorkeeper.add(key);
+        if (this.#doorkeeper.size > DOORKEEPER_KEYS)
+            this.#doorkeeper.delete(this.#doorkeeper.values().next().value);
+    }
+    #remove(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return;
+        const size = entrySize(key, entry.encoded);
+        this.#entries.delete(key);
+        this.#bytes -= size;
+        if (entry.hits === 0)
+            this.#coldBytes -= size;
+    }
+    #age() {
+        this.#puts += 1;
+        if (this.#puts % HIT_AGING_INTERVAL !== 0)
+            return;
+        for (const [key, entry] of this.#entries) {
+            if (entry.hits === 0)
+                continue;
+            entry.hits = Math.floor(entry.hits / 2);
+            if (entry.hits === 0)
+                this.#coldBytes += entrySize(key, entry.encoded);
+        }
     }
     clear() {
         this.#entries.clear();
+        this.#doorkeeper.clear();
         this.#bytes = 0;
+        this.#coldBytes = 0;
     }
     statistics() {
         return {
             hits: this.#hits,
             misses: this.#misses,
             evictions: this.#evictions,
+            rejections: this.#rejections,
             retainedBytes: this.#bytes,
             retainedDocuments: this.#entries.size,
         };
     }
 }
+function entrySize(key, encoded) {
+    return encoded.length + key.length * 2 + 128;
+}
 // All domains call the same parser; cache keys include both bytes and source location.
 // Authorization remains in workspace reads, before any document reaches this cache.
 export const sourceDocuments = new SourceDocumentCache();

package/dist/hoi4_agent_tools/event/service.js

@@ -1308,6 +1308,13 @@ export class EventChainViewer {
         input.signal?.throwIfAborted();
         if (input.proposedSources !== undefined)
             assertProposedSourceBounds(input.proposedSources);
+        // Without references the comparison uses the previous cached revision; with none cached,
+        // say so before scanning the workspace.
+        if (input.before === undefined &&
+            input.after === undefined &&
+            input.proposedSources === undefined &&
+            (this.#state.history.get(input.workspaceId)?.size ?? 0) === 0)
+            throw new ServiceError('EVENT_COMPARISON_BASELINE_REQUIRED', 'Provide a cached revision, graph artifact, or proposed source overlay');
         const refresh = input.refresh ??
             (input.proposedSources !== undefined ||
                 input.before === undefined ||

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -456,6 +456,12 @@ function overlayToSvg(scene, variant) {
         .join('');
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${scene.resolution.width}" height="${scene.resolution.height}" viewBox="0 0 ${scene.resolution.width} ${scene.resolution.height}"><defs>${toolText.definitions()}</defs>${overlays}</svg>`;
 }
+/** The preview backdrop; a transparent scenario leaves uncovered pixels fully transparent. */
+function backdrop(scene, viewBox) {
+    return scene.scenario.background === 'transparent'
+        ? ''
+        : `<rect ${rectAttributes(viewBox)} fill="#17202a"/>`;
+}
 export function sceneToSvg(scene, variant) {
     const view = viewFor(scene, variant);
     assertRenderDimensions(view.width, view.height, `GUI ${variant} SVG`);
@@ -470,7 +476,7 @@ export function sceneToSvg(scene, variant) {
         .map((element) => renderOverlay(element, variant, toolText))
         .join('');
     const fidelity = escapeXml(canonicalJson(scene.fidelity));
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions.join('')}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs><rect ${rectAttributes(view.viewBox)} fill="#17202a"/>${body}${overlays}</svg>`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions.join('')}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs>${backdrop(scene, view.viewBox)}${body}${overlays}</svg>`;
 }
 async function cooperativeParts(values, render, signal) {
     const output = [];
@@ -494,7 +500,7 @@ async function sceneToSvgCooperative(scene, variant, signal) {
     const body = (await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal)) + renderTooltipPreview(scene, toolText);
     const overlays = await cooperativeParts(scene.elements, (element) => renderOverlay(element, variant, toolText), signal);
     const fidelity = escapeXml(canonicalJson(scene.fidelity));
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs><rect ${rectAttributes(view.viewBox)} fill="#17202a"/>${body}${overlays}</svg>`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs>${backdrop(scene, view.viewBox)}${body}${overlays}</svg>`;
 }
 export function hierarchyToSvg(scene) {
     const rows = scene.elements.toSorted((left, right) => left.depth - right.depth || left.zIndex - right.zIndex || compareCodeUnits(left.id, right.id));

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

@@ -459,6 +459,62 @@ function generatedRows(count, random, options) {
         };
     });
 }
+/** Sprite tokens read by scripted GUI `image` properties of the window. */
+function scriptedImageTokens(scripted) {
+    const tokens = new Set();
+    for (const definition of scripted)
+        for (const property of definition.propertyDefinitions)
+            for (const [attribute, expression] of Object.entries(property.attributes)) {
+                const token = expressionToken(expression);
+                if (token !== undefined && attribute.toLocaleLowerCase('en-US') === 'image')
+                    tokens.add(token);
+            }
+    return tokens;
+}
+/**
+ * Resolve the window's scripted localisation exactly under a supplied scenario: a text or
+ * sprite token whose `defined_text` branch the scenario's flags, variables and values decide
+ * takes that branch. A token the scenario cannot decide is left out, so it still renders as
+ * `[dynamic_loc]`, and caller-supplied values always win.
+ */
+export function resolveScenarioScriptedLocalisation(graph, windowName, base, 
+/** Built only when the window shows scripted localisation; building scans every helper. */
+definitions = () => new ClausewitzEvaluationDefinitions()) {
+    if (graph.scriptedLocalisation.length === 0)
+        return base;
+    const scripted = relatedScriptedGuis(graph, windowName);
+    const elements = relevantElements(graph, windowName, scripted);
+    const textual = tokensIn(sourceTexts(graph, elements, base.language, scripted)).textual;
+    const names = new Set(graph.scriptedLocalisation.map(({ name }) => name));
+    const shown = (token) => names.has(token.slice(token.lastIndexOf('.') + 1));
+    const imageTokens = scriptedImageTokens(scripted);
+    if (![...textual, ...imageTokens].some(shown))
+        return base;
+    const evaluation = definitions();
+    const explicitValues = guiExplicitConditionValues(base);
+    const values = { ...base.values };
+    const templates = new Map();
+    const evaluate = (key, kind) => explicitValues[key] !== undefined
+        ? undefined
+        : scriptedLocalisationValue(graph, key, base.language, kind, explicitValues, base, evaluation, []);
+    for (const key of textual) {
+        const template = evaluate(key, 'text');
+        if (template !== undefined)
+            templates.set(key, template);
+    }
+    for (const key of imageTokens) {
+        const sprite = evaluate(key, 'image');
+        if (sprite !== undefined)
+            values[key] = sprite;
+    }
+    // Branch texts can embed further tokens, including other resolved branches.
+    for (let pass = 0; pass < 3; pass += 1)
+        for (const [key, template] of templates)
+            values[key] = materializeDynamicText(template, { ...explicitValues, ...values });
+    return Object.keys(values).length === Object.keys(base.values).length
+        ? base
+        : { ...base, values };
+}
 export function generateGuiPreviewScenarios(graph, windowName, base, options, definitions = new ClausewitzEvaluationDefinitions()) {
     if (!options.enabled)
         return [];

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -145,6 +145,8 @@ const GuiPreviewScenarioBodySchema = z
     conditionResults: z.array(ConditionResultSchema).max(10_000).optional(),
     variables: z.record(z.string(), z.number()).default({}),
     flags: z.record(z.string(), z.boolean()).default({}),
+    closedFlags: z.boolean().optional(),
+    background: z.enum(['scene', 'transparent']).optional(),
     lists: z.record(z.string(), z.array(objectSchema).max(10_000)).default({}),
     localisation: z.record(z.string(), z.string()).default({}),
     values: objectSchema.default({}),

package/dist/hoi4_agent_tools/gui/studio.js

@@ -21,7 +21,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 } from './scenario-generator.js';
+import { generateGuiPreviewScenarios, resolveScenarioScriptedLocalisation, } from './scenario-generator.js';
 import { parseGeneratedScenarioOptions, parsePreviewScenario } from './scenario.js';
 import { buildGuiSourceGraph } from './source-graph.js';
 import { assertGuiSourcePatchesSafe } from './source-patch.js';
@@ -917,6 +917,8 @@ export function guiArtifactProvenance(graph, kind, primaryScene, scenarioScenes
     };
 }
 const sharedGuiGraphs = new WeakMap();
+/** Graphs kept per engine: one for each scope a preview builds, across a few workspaces. */
+const GUI_GRAPH_CACHE_SCOPES = 6;
 export class ScriptedGuiStudio {
     engine;
     resolver;
@@ -953,12 +955,21 @@ 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, this.engine.indexFiles(retainedFiles), additionalLocalisationKeys),
+            graph: buildGuiSourceGraph(retainedFiles, index, additionalLocalisationKeys),
+            index,
         };
+        // 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.
+        for (const existing of this.#graphCache.keys())
+            if (existing.startsWith(`${scope}:`))
+                this.#graphCache.delete(existing);
         this.#graphCache.set(key, scanned);
-        while (this.#graphCache.size > 1) {
+        while (this.#graphCache.size > GUI_GRAPH_CACHE_SCOPES) {
             const oldest = this.#graphCache.keys().next().value;
             if (oldest === undefined)
                 break;
@@ -1004,7 +1015,7 @@ export class ScriptedGuiStudio {
             const gameGraph = this.graphForFiles(gameLayouts.files, `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)));
-            layoutGraph = this.graphForFiles(layoutFiles, `layout:${workspaceId}`).graph;
+            layoutGraph = this.graphForFiles(layoutFiles, `merged-layout:${workspaceId}`).graph;
         }
         if (!layoutGraph.elements.some(({ name }) => name === windowName))
             assertTargetWindowAvailable(layoutGraph, windowName);
@@ -1062,16 +1073,20 @@ export class ScriptedGuiStudio {
             ? 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]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
+        let builtDefinitions;
+        const evaluationDefinitions = () => (builtDefinitions ??= ClausewitzEvaluationDefinitions.build(scanned));
+        const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
+        const suppliedScenario = resolveLocalisation(placeholderScenario);
         const generatedScenarios = generatedOptions === undefined
             ? []
-            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
-        const scenario = generatedScenarios[0] ?? placeholderScenario;
+            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, evaluationDefinitions());
+        const scenario = generatedScenarios[0] ?? suppliedScenario;
         const relatedScenarios = [
             ...(generatedOptions?.preservePlaceholder === true && generatedScenarios.length > 0
-                ? [placeholderScenario]
+                ? [suppliedScenario]
                 : []),
             ...generatedScenarios.slice(1),
-            ...explicitRelatedScenarios,
+            ...explicitRelatedScenarios.map(resolveLocalisation),
         ];
         assertUniqueScenarioIds([scenario, ...relatedScenarios]);
         const budget = new RenderBudget();
@@ -1157,16 +1172,20 @@ export class ScriptedGuiStudio {
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
         ].some(({ tooltip }) => tooltip !== undefined));
+        let builtDefinitions;
+        const evaluationDefinitions = () => (builtDefinitions ??= ClausewitzEvaluationDefinitions.build(scanned));
+        const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
+        const suppliedScenario = resolveLocalisation(placeholderScenario);
         const generatedScenarios = generatedOptions === undefined
             ? []
-            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
-        const scenario = generatedScenarios[0] ?? placeholderScenario;
+            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, evaluationDefinitions());
+        const scenario = generatedScenarios[0] ?? suppliedScenario;
         const relatedScenarios = [
             ...(generatedOptions?.preservePlaceholder === true && generatedScenarios.length > 0
-                ? [placeholderScenario]
+                ? [suppliedScenario]
                 : []),
             ...generatedScenarios.slice(1),
-            ...explicitRelatedScenarios,
+            ...explicitRelatedScenarios.map(resolveLocalisation),
         ];
         assertUniqueScenarioIds([scenario, ...relatedScenarios]);
         const baselineScenario = requestedBaselineScenario ??

package/dist/hoi4_agent_tools/gui/validators.js

@@ -4,6 +4,9 @@ import { sha256Bytes } from '../core/canonical.js';
 import { assertRenderDimensions } from '../core/render-budget.js';
 import { GuiAssetCatalog } from './assets.js';
 import { GUI_GRAPH_MAX_EDGES, GUI_GRAPH_MAX_NODES, GUI_SCENE_MAX_ELEMENTS, GUI_VALIDATION_MAX_ANCESTOR_HOPS, GUI_VALIDATION_MAX_DIAGNOSTICS, GUI_VALIDATION_MAX_PAIR_COMPARISONS, } from './limits.js';
+/** Horizontal offsets from a parent's centre above rounding and up to a few pixels look accidental. */
+const NEAR_CENTRE_TOLERANCE_PX = 0.5;
+const NEAR_CENTRE_MAX_PX = 3;
 const allStates = [
     'normal',
     'hover',
@@ -435,6 +438,19 @@ function validateOverlapAndGeometry(scene, diagnostics, work) {
     const visible = scene.elements.filter((element) => element.visible && area(element.rect) > 0);
     const byId = new Map(scene.elements.map((element) => [element.id, element]));
     for (const element of scene.elements) {
+        // An element a few pixels from its parent's horizontal centre was almost always meant
+        // to be centred; larger offsets are deliberate placement.
+        const parent = element.parentId === undefined ? undefined : byId.get(element.parentId);
+        if (element.visible &&
+            parent?.visible === true &&
+            element.unclippedRect.width > 0 &&
+            element.unclippedRect.width < parent.unclippedRect.width - 2) {
+            const offset = element.unclippedRect.x +
+                element.unclippedRect.width / 2 -
+                (parent.unclippedRect.x + parent.unclippedRect.width / 2);
+            if (Math.abs(offset) > NEAR_CENTRE_TOLERANCE_PX && Math.abs(offset) <= NEAR_CENTRE_MAX_PX)
+                diagnostics.push(issue('GUI_NEAR_CENTRE_OFFSET', 'warning', 'layout', `${element.name} sits ${Math.abs(offset).toFixed(1)} px ${offset > 0 ? 'right' : 'left'} of the centre of ${parent.name}; centre it exactly or offset it clearly.`, element, { parent: parent.id, offset }));
+        }
         if (element.unclippedRect.width <= 0 || element.unclippedRect.height <= 0) {
             diagnostics.push(issue('GUI_INVALID_SIZE', 'warning', 'layout', `${element.name} has a non-positive ${element.unclippedRect.width}x${element.unclippedRect.height} size.`, element));
         }
@@ -477,6 +493,12 @@ function validateOverlapAndGeometry(scene, diagnostics, work) {
                 if (left.clickable && right.clickable && ratio > 0.02) {
                     diagnostics.push(issue('GUI_CONFLICTING_CLICK_REGIONS', 'error', 'design', `${left.name} and ${right.name} have overlapping click regions (${(ratio * 100).toFixed(1)}%).`, right, { left: left.id, right: right.id, ratio }));
                 }
+                // Tab pages and alternative panels overlap by design; the game shows one at a time.
+                // When the scenario cannot decide which, the preview draws them stacked.
+                if (left.depth === right.depth &&
+                    ratio > 0.2 &&
+                    (left.visibilityStatus === 'unresolved' || right.visibilityStatus === 'unresolved'))
+                    diagnostics.push(issue('GUI_UNRESOLVED_VISIBILITY_OVERLAP', 'warning', 'layout', `${left.name} and ${right.name} overlap and the scenario does not decide which is visible, so the preview draws both. Declare the flags or variables their visible triggers read, with closedFlags, to render one of them.`, right, { left: left.id, right: right.id, ratio }));
                 if (left.depth === right.depth && ratio > 0.2) {
                     diagnostics.push(issue('GUI_VISIBLE_OVERLAP', 'warning', 'layout', `${left.name} and ${right.name} overlap by ${(ratio * 100).toFixed(1)}% of the smaller element.`, right, { left: left.id, right: right.id, ratio }));
                 }

package/dist/hoi4_agent_tools/mcp/resources/register-modern.js

@@ -1,14 +1,26 @@
 import { ReadResourceResultSchema } from '@modelcontextprotocol/core';
 import { ProtocolError, ProtocolErrorCode, ResourceNotFoundError, } from '@modelcontextprotocol/server';
 import { artifactResourceDefinition, readArtifactResource } from '../../core/artifact-resource.js';
+import { readServerStatus, serverStatusResource } from '../../core/server-status-resource.js';
 import { ServiceError } from '../../core/result.js';
 /** Modern wire projection of the same non-enumerating, authorization-bound resource reader. */
 export function registerModernResources(server, engine, context) {
-    server.setRequestHandler('resources/list', () => ({ resources: [] }));
+    // Process details are offered to the local client only, never to authenticated remote ones.
+    const local = context.principal === undefined;
+    server.setRequestHandler('resources/list', () => ({
+        resources: local ? [serverStatusResource] : [],
+    }));
     server.setRequestHandler('resources/templates/list', () => ({
         resourceTemplates: [artifactResourceDefinition],
     }));
     server.setRequestHandler('resources/read', async (request, extra) => {
+        if (local && request.params.uri === serverStatusResource.uri)
+            return ReadResourceResultSchema.parse({
+                ...(await readServerStatus(engine)),
+                resultType: 'complete',
+                ttlMs: 0,
+                cacheScope: 'private',
+            });
         try {
             return ReadResourceResultSchema.parse({
                 ...(await readArtifactResource(engine, request.params.uri, context, extra.mcpReq.signal)),

package/dist/hoi4_agent_tools/mcp/resources/register.js

@@ -1,7 +1,13 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { artifactResourceDefinition, readArtifactResource } from '../../core/artifact-resource.js';
+import { readServerStatus, serverStatusResource } from '../../core/server-status-resource.js';
 /** SDK-v1 registration only; ownership and byte-range behavior live in the shared core. */
 export function registerMcpResources(server, engine, context) {
     const { name, uriTemplate, ...metadata } = artifactResourceDefinition;
     server.registerResource(name, new ResourceTemplate(uriTemplate, { list: undefined }), metadata, (uri, _variables, extra) => readArtifactResource(engine, uri.href, context, extra.signal));
+    // Process details are offered to the local client only, never to authenticated remote ones.
+    if (context.principal !== undefined)
+        return;
+    const { name: statusName, uri: statusUri, ...statusMetadata } = serverStatusResource;
+    server.registerResource(statusName, statusUri, statusMetadata, () => readServerStatus(engine));
 }

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

@@ -44,7 +44,7 @@ export const referenceTools = [
     {
         name: 'hoi4.script_validate',
         title: 'Check HOI4 script commands and scopes',
-        description: 'Check effect or trigger snippet syntax, native command kinds and declared scopes against cited installed documentation. Unknown helpers and native argument blocks remain explicit.',
+        description: 'Check an effect or trigger snippet (source, kind, scope) or a whole mod file (path) for syntax, native command kinds and scopes against cited installed documentation. Unknown helpers and native argument blocks remain explicit.',
         inputSchema: scriptValidateRequestSchema,
         outputSchema: strictOperationResultSchema(scriptValidateDataSchema),
         annotations: readOnly,

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

@@ -1,7 +1,7 @@
 import { registerLegacyTaskTools } from '../server/legacy-task-tools.js';
 import { z } from 'zod/v4';
 import { helperExpansionRequestSchema, helperExpansionSummarySchema, } from '../../schemas/helper-expansion.js';
-import { technologyAnalysisModeSchema, technologyCompareRequestSchema, technologyGraphReferenceSchema, technologyImpactSchema, technologyInspectRequestSchema, technologyProposedSourceSchema, technologyRenderRequestSchema, technologyRenderViewSchema, validateTechnologyCompareRequest, validateTechnologyInspectRequest, } from '../../schemas/technology.js';
+import { technologyAnalysisModeSchema, technologyCompareRequestSchema, technologyGraphReferenceSchema, technologyImpactSchema, technologyInspectRequestSchema, technologyProposedSourceSchema, technologyRenderRequestSchema, validateTechnologyRenderRequest, technologyRenderViewSchema, validateTechnologyCompareRequest, validateTechnologyInspectRequest, } from '../../schemas/technology.js';
 import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { nonNegativeIntegerSchema, sha256Schema } from '../server/output-schemas.js';
 import { strictOperationResultSchema } from '../server/result.js';
@@ -13,7 +13,10 @@ const inspectInputSchema = z
 })
     .strict()
     .superRefine(validateTechnologyInspectRequest);
-const renderInputSchema = z.object({ ...technologyRenderRequestSchema.shape }).strict();
+const renderInputSchema = z
+    .object({ ...technologyRenderRequestSchema.shape })
+    .strict()
+    .superRefine(validateTechnologyRenderRequest);
 const compareInputSchema = z
     .object({
     ...technologyCompareRequestSchema.shape,

package/dist/hoi4_agent_tools/mcp/transports/negotiated-stdio.js

@@ -80,12 +80,21 @@ export async function serveNegotiatedStdio(engine, options) {
         reportedErrors.add(error);
         options.onerror(error);
     };
+    const observer = options.observer;
+    if (observer !== undefined) {
+        const send = physical.send.bind(physical);
+        physical.send = (message) => {
+            observer.sent(message);
+            return send(message);
+        };
+    }
     physical.onclose = () => pinned?.onclose();
     physical.onerror = (error) => {
         reportError(error);
         pinned?.onerror(error);
     };
     physical.onmessage = (message) => {
+        observer?.received(message);
         if (pinned === undefined) {
             pinned = new PinnedStdioTransport(physical, reportError);
             try {

package/dist/hoi4_agent_tools/mcp/transports/stdio-lifetime.js

@@ -0,0 +1,79 @@
+/**
+ * Ends a stdio server that no client can reach. A client normally closes stdin, which the
+ * transport turns into a clean exit. Two cases leave stdin open: the launching process
+ * (for example a `cmd.exe` shim that a client terminated) dies while the client keeps the
+ * pipe, and a client keeps an idle connection it will never use again. The first is detected
+ * by polling the parent process; the second by an optional idle limit.
+ */
+import { processAlive } from '../../core/server-registry.js';
+const PARENT_POLL_MS = 5_000;
+export { processAlive };
+export class StdioLifetime {
+    #options;
+    #open = new Set();
+    #lastActivity;
+    #timer;
+    #stopped = false;
+    constructor(options) {
+        this.#options = {
+            parentPid: options.parentPid ?? process.ppid,
+            isAlive: options.isAlive ?? processAlive,
+            now: options.now ?? Date.now,
+            pollMs: options.pollMs ?? PARENT_POLL_MS,
+            idleExitMinutes: options.idleExitMinutes,
+            onExit: options.onExit,
+        };
+        this.#lastActivity = this.#options.now();
+    }
+    start() {
+        this.#timer = setInterval(() => this.check(), this.#options.pollMs);
+        // The poll never keeps an otherwise finished server alive.
+        this.#timer.unref();
+    }
+    stop() {
+        this.#stopped = true;
+        if (this.#timer !== undefined)
+            clearInterval(this.#timer);
+    }
+    /** A client message: a request opens until its response is sent. */
+    received(message) {
+        this.#lastActivity = this.#options.now();
+        const id = requestId(message, 'method');
+        if (id !== undefined)
+            this.#open.add(id);
+    }
+    /** A server message: a response closes its request. */
+    sent(message) {
+        this.#lastActivity = this.#options.now();
+        const id = requestId(message, 'result') ?? requestId(message, 'error');
+        if (id !== undefined)
+            this.#open.delete(id);
+    }
+    /** When the client last sent or received a message, in epoch milliseconds. */
+    lastActivity() {
+        return this.#lastActivity;
+    }
+    check() {
+        if (this.#stopped)
+            return;
+        const { parentPid, isAlive, idleExitMinutes, now, onExit } = this.#options;
+        // A parent pid of 0 or 1 means the server was already reparented at start.
+        if (parentPid > 1 && !isAlive(parentPid)) {
+            this.stop();
+            onExit('parent_exited');
+            return;
+        }
+        if (idleExitMinutes > 0 &&
+            this.#open.size === 0 &&
+            now() - this.#lastActivity > idleExitMinutes * 60_000) {
+            this.stop();
+            onExit('idle');
+        }
+    }
+}
+function requestId(message, field) {
+    if (typeof message !== 'object' || message === null || !(field in message))
+        return undefined;
+    const id = message.id;
+    return typeof id === 'string' || typeof id === 'number' ? id : undefined;
+}