hoi4-agent-tools 2.3.13 → 2.5.0

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

@@ -49,6 +49,7 @@ const guiRenderOutputSchema = strictOperationResultSchema(z
         .strict())
         .max(64),
     stateCount: nonNegativeIntegerSchema,
+    scenarioCount: nonNegativeIntegerSchema,
     resolutionCount: nonNegativeIntegerSchema,
     comparison: z
         .object({ changedPixels: nonNegativeIntegerSchema, changedRatio: z.number().min(0).max(1) })
@@ -281,6 +282,9 @@ export function registerGuiTools(server, engine, context) {
                             ...(uiScale === undefined ? {} : { uiScale }),
                         })),
                     }),
+                ...(input.relatedScenarios === undefined
+                    ? {}
+                    : { relatedScenarios: input.relatedScenarios }),
                 ...(input.comparisonScenario === undefined
                     ? {}
                     : { comparisonScenario: input.comparisonScenario }),
@@ -300,6 +304,7 @@ export function registerGuiTools(server, engine, context) {
                     height,
                 })),
                 stateCount: rendered.stateScenes.length,
+                scenarioCount: rendered.scenarioScenes.length,
                 resolutionCount: rendered.resolutionScenes.length,
                 comparison: {
                     changedPixels: rendered.comparison.changedPixels,
@@ -327,10 +332,11 @@ export function registerGuiTools(server, engine, context) {
         .extend({
         states: z.array(previewStateSchema).max(14).optional(),
         resolutions: z.array(resolutionSchema).min(1).max(16).optional(),
+        relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
         comparisonScenario: compactGuiScenarioSchema.optional(),
     })
         .strict()
-        .superRefine(({ scenario, states, resolutions }, context) => {
+        .superRefine(({ scenario, states, resolutions, relatedScenarios }, context) => {
         const budget = new RenderBudget();
         try {
             const stateCount = states?.length ?? 14;
@@ -345,6 +351,7 @@ export function registerGuiTools(server, engine, context) {
             ]) {
                 budget.reserve(resolution.width, resolution.height, 'GUI resolution variant');
             }
+            const scenarioCount = 1 + (relatedScenarios?.length ?? 0);
             const stateColumns = Math.min(3, Math.max(1, stateCount));
             const stateRows = Math.max(1, Math.ceil(stateCount / stateColumns));
             budget.reserve(stateColumns * 420, 46 + stateRows * 280, 'GUI state gallery');
@@ -352,6 +359,10 @@ export function registerGuiTools(server, engine, context) {
             const resolutionColumns = Math.min(3, Math.max(1, resolutionCount));
             const resolutionRows = Math.max(1, Math.ceil(resolutionCount / resolutionColumns));
             budget.reserve(resolutionColumns * 420, 46 + resolutionRows * 280, 'GUI resolution gallery');
+            const scenarioBudget = new RenderBudget();
+            const scenarioColumns = Math.min(3, Math.max(1, scenarioCount));
+            const scenarioRows = Math.max(1, Math.ceil(scenarioCount / scenarioColumns));
+            scenarioBudget.reserve(scenarioColumns * 420, 46 + scenarioRows * 280, 'GUI scripted scenario gallery');
         }
         catch (error) {
             if (error instanceof ServiceError) {
@@ -363,7 +374,7 @@ export function registerGuiTools(server, engine, context) {
     });
     server.registerTool('hoi4.gui_render', {
         title: 'Render scripted GUI artifacts',
-        description: 'Render deterministic offline review artifacts for one GUI window and scenario.',
+        description: 'Render deterministic GUI review artifacts, named value-driven scenario variants, generic states, resolutions, click regions, hierarchy, comparisons, and layout diagnostics.',
         inputSchema: renderInput,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,

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

@@ -39,10 +39,10 @@ const inspectInput = z
 })
     .strict()
     .superRefine((value, context) => {
-    if ((value.adapter === undefined) !== (value.source === undefined))
+    if (value.adapter !== undefined && value.source === undefined)
         context.addIssue({
             code: 'custom',
-            message: 'Provide adapter and source together, or omit both to list adapters',
+            message: 'An adapter requires a source; provide a source alone to discover compatible adapters',
         });
 });
 const evaluateInput = z.object(commonShape).strict();
@@ -135,9 +135,32 @@ const inspectDataSchema = z
     .object({
     adapters: nonNegativeIntegerSchema,
     adapterId: z.string().max(256).optional(),
+    requestedAdapter: z.string().max(256).optional(),
+    suggestedAdapter: z.string().max(256).optional(),
+    discoveryReason: z
+        .enum([
+        'source_inventory',
+        'requested_adapter_empty',
+        'identifier_not_found',
+        'candidate_pool_not_found',
+        'no_weighted_surfaces',
+    ])
+        .optional(),
     sourceRevision: sha256Schema.optional(),
     sourceHash: sha256Schema.optional(),
     candidates: nonNegativeIntegerSchema,
+    availableCandidates: nonNegativeIntegerSchema,
+    availableAdapters: z
+        .array(z
+        .object({
+        adapterId: z.string().max(256),
+        candidates: nonNegativeIntegerSchema,
+        identifierMatches: nonNegativeIntegerSchema,
+        candidatePoolMatches: nonNegativeIntegerSchema,
+    })
+        .strict())
+        .max(10),
+    candidateExamples: z.array(z.string().max(512)).max(10),
     poolComplete: z.boolean().optional(),
     requiredInputs: nonNegativeIntegerSchema,
     unresolved: nonNegativeIntegerSchema,
@@ -211,7 +234,7 @@ export function registerProbabilityTools(server, engine, context) {
     const analyzer = new ProbabilityAnalyzer(engine);
     server.registerTool('hoi4.probability_inspect', {
         title: 'Inspect AI and MTTH weighted logic',
-        description: 'List versioned adapters or discover weighted blocks, candidate pools, capabilities, provenance, and unsupported constructs.',
+        description: 'List versioned adapters, or provide a source alone to discover compatible weighted adapters, candidate pools, capabilities, provenance, and unsupported constructs before narrowing the request.',
         inputSchema: inspectInput,
         outputSchema: inspectOutput,
         annotations: readOnly,
@@ -231,14 +254,37 @@ export function registerProbabilityTools(server, engine, context) {
                         sourceHash: inspected.surface.sourceHash,
                         poolComplete: inspected.surface.poolComplete,
                     }),
+                ...(inspected.discovery === undefined
+                    ? {}
+                    : {
+                        ...(inspected.discovery.requestedAdapter === undefined
+                            ? {}
+                            : { requestedAdapter: inspected.discovery.requestedAdapter }),
+                        ...(inspected.discovery.suggestedAdapter === undefined
+                            ? {}
+                            : { suggestedAdapter: inspected.discovery.suggestedAdapter }),
+                        discoveryReason: inspected.discovery.reason,
+                        sourceRevision: inspected.discovery.sourceRevision,
+                        sourceHash: inspected.discovery.sourceHash,
+                    }),
                 candidates: inspected.surface?.candidateCount ?? 0,
+                availableCandidates: inspected.discovery?.availableAdapters.reduce((sum, { candidateCount }) => sum + candidateCount, 0) ?? 0,
+                availableAdapters: inspected.discovery?.availableAdapters.map((available) => ({
+                    adapterId: available.adapterId,
+                    candidates: available.candidateCount,
+                    identifierMatches: available.identifierMatchCount,
+                    candidatePoolMatches: available.candidatePoolMatchCount,
+                })) ?? [],
+                candidateExamples: inspected.discovery?.exampleCandidateIds ?? [],
                 requiredInputs: inspected.surface?.requiredInputs.length ?? 0,
                 unresolved: inspected.surface?.unsupported.length ?? 0,
             });
             result.code =
-                inspected.surface === undefined
-                    ? 'PROBABILITY_ADAPTERS_LISTED'
-                    : 'PROBABILITY_SOURCE_INSPECTED';
+                inspected.surface !== undefined
+                    ? 'PROBABILITY_SOURCE_INSPECTED'
+                    : inspected.discovery !== undefined
+                        ? 'PROBABILITY_SOURCE_DISCOVERED'
+                        : 'PROBABILITY_ADAPTERS_LISTED';
             result.artifacts = inspected.artifacts;
             setInlineFilesScanned(result, inspected.filesScanned);
             await progress.report(2, 2, 'Weighted source inspection complete');

package/dist/hoi4_agent_tools/probability/service.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { canonicalJson, hashCanonical } from '../core/canonical.js';
+import { canonicalJson, compareCodeUnits, hashCanonical } from '../core/canonical.js';
 import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
 import { probabilityDomainScanPatterns } from '../core/domain-scan-patterns.js';
 import { publicArtifactLink } from '../core/artifacts.js';
@@ -13,7 +13,7 @@ import { VERIFIED_GAME_CHECKSUM, VERIFIED_GAME_RAW_VERSION, VERIFIED_GAME_VERSIO
 import { renderProbabilityResult } from './render.js';
 import { analyzeSequence } from './sequence.js';
 import { simulateSurface } from './simulation.js';
-import { discoverWeightedSurface } from './source-analysis.js';
+import { discoverWeightedSurface, inventoryWeightedSurfaces, } from './source-analysis.js';
 import { sweepSurface } from './sweep.js';
 const states = new WeakMap();
 function analyzerState(engine) {
@@ -775,18 +775,92 @@ export class ProbabilityAnalyzer {
         return complete;
     }
     async inspect(context, adapter, source, candidatePool = []) {
-        if (adapter === undefined || source === undefined)
+        if (source === undefined)
             return { adapters: probabilityAdapters(), artifacts: [], filesScanned: [] };
-        const gameVersionVerification = await this.verifyGameVersion(context, adapter);
         const snapshot = await this.scan(context, [source.path]);
-        const surface = discoverWeightedSurface(snapshot, adapter, source, candidatePool);
+        const storeDiscovery = async (inventory, reason) => {
+            const availableAdapters = inventory.adapters.filter(({ candidateCount }) => candidateCount > 0);
+            const matchingIdentifier = availableAdapters.filter(({ identifierMatchCount }) => source.identifier !== undefined && identifierMatchCount > 0);
+            const matchingPool = availableAdapters.filter(({ candidatePoolMatchCount }) => candidatePool.length > 0 && candidatePoolMatchCount > 0);
+            const requested = availableAdapters.find(({ adapterId }) => adapterId === adapter);
+            const ranked = [
+                ...(matchingIdentifier.length > 0
+                    ? matchingIdentifier
+                    : matchingPool.length > 0
+                        ? matchingPool
+                        : requested === undefined
+                            ? availableAdapters
+                            : [requested]),
+            ].sort((left, right) => right.identifierMatchCount - left.identifierMatchCount ||
+                right.candidatePoolMatchCount - left.candidatePoolMatchCount ||
+                right.candidateCount - left.candidateCount ||
+                compareCodeUnits(left.adapterId, right.adapterId));
+            const suggested = ranked[0];
+            const discovery = {
+                ...(adapter === undefined ? {} : { requestedAdapter: adapter }),
+                reason,
+                sourceRevision: inventory.sourceRevision,
+                sourceHash: inventory.sourceHash,
+                availableAdapters,
+                ...(suggested === undefined ? {} : { suggestedAdapter: suggested.adapterId }),
+                exampleCandidateIds: suggested?.exampleCandidateIds ?? [],
+            };
+            const report = {
+                schemaVersion: 'probability-inspection.v2',
+                workspaceId: context.workspaceId,
+                discovery,
+            };
+            const workspace = this.engine.resolver.get(context.workspaceId, context.principal);
+            const artifact = await this.engine.artifacts.putChunked(workspace, `probability-inspect-${inventory.sourceHash.slice(0, 12)}.json`, 'application/json', `${canonicalJson(report)}\n`, {
+                kind: 'probability-inspection',
+                toolVersion: PACKAGE_VERSION,
+                schemaVersion: 'probability-inspection.v2',
+                sourceHashes: { aggregate: inventory.sourceHash },
+            }, 'Weighted-source adapter inventory and candidate examples', context.signal);
+            return {
+                adapters: probabilityAdapters(),
+                discovery,
+                artifacts: [publicArtifactLink(artifact)],
+                filesScanned: inventory.filesScanned,
+            };
+        };
+        if (adapter === undefined) {
+            const inventory = inventoryWeightedSurfaces(snapshot, source, candidatePool);
+            return storeDiscovery(inventory, inventory.adapters.some(({ candidateCount }) => candidateCount > 0)
+                ? 'source_inventory'
+                : 'no_weighted_surfaces');
+        }
+        const gameVersionVerification = await this.verifyGameVersion(context, adapter);
+        let surface;
+        try {
+            surface = discoverWeightedSurface(snapshot, adapter, source, candidatePool);
+        }
+        catch (error) {
+            if (!(error instanceof ServiceError) ||
+                (error.code !== 'PROBABILITY_SURFACE_EMPTY' &&
+                    error.code !== 'PROBABILITY_IDENTIFIER_NOT_FOUND'))
+                throw error;
+            const inventory = inventoryWeightedSurfaces(snapshot, source, candidatePool);
+            const requested = inventory.adapters.find(({ adapterId }) => adapterId === adapter);
+            const reason = error.code === 'PROBABILITY_IDENTIFIER_NOT_FOUND'
+                ? 'identifier_not_found'
+                : requested !== undefined &&
+                    requested.candidateCount > 0 &&
+                    candidatePool.length > 0 &&
+                    requested.candidatePoolMatchCount === 0
+                    ? 'candidate_pool_not_found'
+                    : inventory.adapters.every(({ candidateCount }) => candidateCount === 0)
+                        ? 'no_weighted_surfaces'
+                        : 'requested_adapter_empty';
+            return storeDiscovery(inventory, reason);
+        }
         const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
         const inspectedCandidates = evaluateExactCandidates(surface, { id: 'inspection', state: {} }, definitions);
         const requiredInputs = [
             ...new Set(inspectedCandidates.flatMap(({ unresolved }) => unresolved.flatMap(({ path }) => (path === undefined ? [] : [path])))),
         ].sort();
         const report = {
-            schemaVersion: 'probability-inspection.v1',
+            schemaVersion: 'probability-inspection.v2',
             workspaceId: context.workspaceId,
             surface: {
                 id: surface.id,
@@ -826,7 +900,7 @@ export class ProbabilityAnalyzer {
         const artifact = await this.engine.artifacts.putChunked(workspace, `probability-inspect-${surface.sourceHash.slice(0, 12)}.json`, 'application/json', `${canonicalJson(report)}\n`, {
             kind: 'probability-inspection',
             toolVersion: PACKAGE_VERSION,
-            schemaVersion: 'probability-inspection.v1',
+            schemaVersion: 'probability-inspection.v2',
             sourceHashes: { aggregate: surface.sourceHash },
         }, 'Discovered weighted surfaces and adapter capabilities', context.signal);
         return {

package/dist/hoi4_agent_tools/probability/source-analysis.js

@@ -2,6 +2,18 @@ import { compareCodeUnits, hashCanonical } from '../core/canonical.js';
 import { ServiceError } from '../core/result.js';
 import { assignments, astPathFor, childBlocks, firstScalar, nodeLocation, parseClausewitz, } from '../core/source/index.js';
 import { probabilityAdapter } from './adapters.js';
+const sourceBackedAdapterIds = [
+    'event_mean_time_to_happen',
+    'event_option_ai_chance',
+    'decision_ai_will_do',
+    'mission_ai_will_do',
+    'national_focus_ai_will_do',
+    'technology_ai_will_do',
+    'doctrine_ai_will_do',
+    'direct_random',
+    'random_list',
+    'ai_strategy_factor',
+];
 const eventKeys = new Set([
     'country_event',
     'news_event',
@@ -116,6 +128,9 @@ function focusCandidates(context) {
     return output;
 }
 function decisionCandidates(context, adapterId) {
+    const sourcePath = normalized(context.file.relativePath);
+    if (context.file.absolutePath !== '<inline>' && !sourcePath.startsWith('common/decisions/'))
+        return [];
     const output = [];
     const ignored = new Set([
         'allowed',
@@ -131,6 +146,10 @@ function decisionCandidates(context, adapterId) {
     for (const { assignment, ancestors } of walkAssignments(context.document.root)) {
         if (assignment.value.type !== 'block' ||
             ancestors.length !== 1 ||
+            ancestors[0].key === 'focus_tree' ||
+            ancestors[0].key === 'continuous_focus_palette' ||
+            ancestors[0].key === 'technologies' ||
+            eventKeys.has(ancestors[0].key) ||
             ignored.has(assignment.key.value))
             continue;
         const mission = firstScalar(assignment.value, 'is_mission')?.value === 'yes' ||
@@ -353,42 +372,74 @@ function samePool(candidate, selected) {
         return candidate.metadata.randomListId === selected.metadata.randomListId;
     return candidate.id === selected.id;
 }
+function candidatesAtSourceLine(candidates, adapterId, line) {
+    if (line === undefined)
+        return candidates;
+    let selected = candidates.filter(({ metadata, provenance: [first] }) => {
+        const location = first?.location;
+        const poolStartLine = metadata.poolStartLine;
+        const poolEndLine = metadata.poolEndLine;
+        return ((location !== undefined && line >= location.start.line && line <= location.end.line) ||
+            (typeof poolStartLine === 'number' &&
+                typeof poolEndLine === 'number' &&
+                line >= poolStartLine &&
+                line <= poolEndLine));
+    });
+    if (adapterId !== 'event_option_ai_chance' && adapterId !== 'random_list')
+        return selected;
+    const poolProperty = adapterId === 'event_option_ai_chance' ? 'eventId' : 'randomListId';
+    const pools = new Map();
+    for (const candidate of selected) {
+        const start = candidate.metadata.poolStartLine;
+        const end = candidate.metadata.poolEndLine;
+        const span = typeof start === 'number' && typeof end === 'number' ? end - start : Number.MAX_SAFE_INTEGER;
+        const key = candidate.metadata[poolProperty];
+        const existing = pools.get(key);
+        if (existing === undefined || span < existing.span)
+            pools.set(key, { span });
+    }
+    const selectedPool = [...pools].sort(([leftKey, left], [rightKey, right]) => left.span - right.span || compareCodeUnits(String(leftKey), String(rightKey)))[0]?.[0];
+    if (selectedPool !== undefined)
+        selected = selected.filter((candidate) => candidate.metadata[poolProperty] === selectedPool);
+    return selected;
+}
+export function inventoryWeightedSurfaces(snapshot, source, candidatePool = [], adapterIds = sourceBackedAdapterIds) {
+    const contexts = sourceContexts(snapshot, source);
+    const wanted = new Set(candidatePool);
+    const adapters = adapterIds
+        .filter((adapterId) => adapterId !== 'custom_weighted_pool')
+        .map((adapterId) => {
+        const candidates = candidatesAtSourceLine(contexts.flatMap((context) => candidatesFor(context, adapterId)), adapterId, source.line).sort((left, right) => compareCodeUnits(left.id, right.id));
+        return {
+            adapterId,
+            candidateCount: candidates.length,
+            identifierMatchCount: source.identifier === undefined
+                ? candidates.length
+                : candidates.filter((candidate) => identifierMatches(candidate, source.identifier))
+                    .length,
+            candidatePoolMatchCount: candidatePool.length === 0
+                ? candidates.length
+                : candidates.filter(({ id }) => wanted.has(id)).length,
+            exampleCandidateIds: [...new Set(candidates.map(({ id }) => id))].slice(0, 10),
+            sourcePaths: [
+                ...new Set(candidates.flatMap(({ provenance }) => provenance.map(({ path }) => path))),
+            ].sort(compareCodeUnits),
+        };
+    })
+        .sort((left, right) => compareCodeUnits(left.adapterId, right.adapterId));
+    const hashes = Object.fromEntries(contexts.map(({ file }) => [file.displayPath, file.sha256]));
+    return {
+        sourceRevision: snapshot.revision,
+        sourceHash: hashCanonical(hashes),
+        filesScanned: contexts.map(({ file }) => file.displayPath),
+        adapters,
+    };
+}
 export function discoverWeightedSurface(snapshot, adapterId, source, candidatePool = []) {
     const contexts = sourceContexts(snapshot, source);
     let candidates = contexts.flatMap((context) => candidatesFor(context, adapterId));
     candidates.sort((left, right) => compareCodeUnits(left.id, right.id));
-    if (source.line !== undefined) {
-        candidates = candidates.filter(({ metadata, provenance: [first] }) => {
-            const location = first?.location;
-            const poolStartLine = metadata.poolStartLine;
-            const poolEndLine = metadata.poolEndLine;
-            return ((location !== undefined &&
-                source.line >= location.start.line &&
-                source.line <= location.end.line) ||
-                (typeof poolStartLine === 'number' &&
-                    typeof poolEndLine === 'number' &&
-                    source.line >= poolStartLine &&
-                    source.line <= poolEndLine));
-        });
-        if (adapterId === 'event_option_ai_chance' || adapterId === 'random_list') {
-            const poolProperty = adapterId === 'event_option_ai_chance' ? 'eventId' : 'randomListId';
-            const pools = new Map();
-            for (const candidate of candidates) {
-                const start = candidate.metadata.poolStartLine;
-                const end = candidate.metadata.poolEndLine;
-                const span = typeof start === 'number' && typeof end === 'number'
-                    ? end - start
-                    : Number.MAX_SAFE_INTEGER;
-                const key = candidate.metadata[poolProperty];
-                const existing = pools.get(key);
-                if (existing === undefined || span < existing.span)
-                    pools.set(key, { span });
-            }
-            const selectedPool = [...pools].sort(([leftKey, left], [rightKey, right]) => left.span - right.span || compareCodeUnits(String(leftKey), String(rightKey)))[0]?.[0];
-            if (selectedPool !== undefined)
-                candidates = candidates.filter((candidate) => candidate.metadata[poolProperty] === selectedPool);
-        }
-    }
+    candidates = candidatesAtSourceLine(candidates, adapterId, source.line);
     const localCategoricalPool = adapterId === 'event_option_ai_chance' || adapterId === 'random_list';
     let completeLocalPoolIds;
     if (source.identifier !== undefined) {

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '2.3.13';
+export const PACKAGE_VERSION = '2.5.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/focus.md

@@ -44,7 +44,7 @@ If malformed or unsupported script makes a requested change ambiguous, the rewri
 
 ## What inspection checks
 
-Inspection and rendering can report missing references, invalid prerequisite structure, duplicate or overlapping positions, insufficient spacing, long or crossing connectors, branch asymmetry, route conflicts, missing localisation or sprites, weak terminal branches, repeated rewards, and missing AI metadata. Renders are offline review artifacts, not game screenshots.
+Inspection and rendering can report missing references, invalid prerequisite structure, duplicate or overlapping positions, insufficient spacing, long or crossing connectors, branch asymmetry, route conflicts, missing localisation or sprites, weak terminal branches, repeated rewards, and missing AI metadata. National-tree inspection also returns the exact `continuous_focus_position` coordinates and linked palette IDs in its compact result, so an agent can identify and move the continuous-focus area without opening the full artifact. Renders are offline review artifacts, not game screenshots.
 
 `hoi4.focus_render` is the normal structural view and writes complete HTML, SVG, JSON, and source-map artifacts without decoding every icon or creating a PNG. `hoi4.focus_raster` adds decoded icons and the high-fidelity PNG. National trees with 200 or more focuses raster at half scale by default; pass `reviewScale` from `0.25` through `1` when a different PNG size is needed.
 

package/docs/gui.md

@@ -24,11 +24,31 @@ Rewrite once, then inspect and render the result.
 
 1. Inspect the root window and its linked GUI, GFX, scripted-GUI, and localisation source.
 2. Render the normal state and the states relevant to the task, such as hover, selected, disabled, warning, empty list, full list, minimum value, maximum value, or long text.
-3. Check common resolutions and UI scales when positioning or clipping can change.
-4. Fix the existing mod-owned file with targeted patches, a complete supported source replacement, or a structured helper replacement.
-5. Rewrite once, then inspect and render the result.
-
-Inspection checks missing assets and localisation, invalid sizes, overlap, clipping, overflow, conflicting click regions, invisible blockers, broken parents or contexts, list-row cuts, state conflicts, trigger/effect gaps, and resolution drift.
+3. Add `relatedScenarios` for every meaningful value-driven version of the window, such as open and closed panels, empty and populated lists, unlocked and locked actions, low and high values, and alternate scripted-GUI property results.
+4. Check common resolutions and UI scales when positioning or clipping can change.
+5. Fix the existing mod-owned file with targeted patches, a complete supported source replacement, or a structured helper replacement.
+6. Rewrite once, then inspect and render the result.
+
+Inspection checks missing assets and localisation, invalid sizes, overlap, clipping, overflow, button-label centering, content crossing a background boundary, conflicting click regions, invisible blockers, broken parents or contexts, list-row cuts, state conflicts, trigger/effect gaps, and resolution drift. `hoi4.gui_render` returns a scripted-scenario gallery and JSON delta report alongside the generic state and resolution galleries.
+
+Preview scenarios can include exact layout expectations:
+
+```json
+{
+  "id": "populated-unlocked",
+  "flags": { "panel_open": true },
+  "lists": { "target_list": [{ "id": 1, "label": "First target" }] },
+  "visibility": { "target_list": true, "confirm_button": true },
+  "expectations": {
+    "visible": ["target_list", "confirm_button"],
+    "hidden": ["empty_message"],
+    "containedBy": { "confirm_button": "main_panel" },
+    "centeredOn": { "confirm_label": "confirm_button" }
+  }
+}
+```
+
+Selectors accept an element name, instance ID, or source ID. Visibility expectations diagnose elements that are missing or in the wrong scripted version. `containedBy` diagnoses text or controls that leave their intended background or panel. `centeredOn` uses rendered glyph bounds, so it catches labels that occupy the right text box but are visibly off-center on the button.
 
 Broad inspection indexes localisation actually referenced by GUI source and returns a connected workspace projection when the complete source graph is very large. The resource records full and returned node and edge counts, so an agent can identify the relevant window without loading unrelated vanilla UI into its prompt. Rendering remains targeted to the selected root, state, and resolution.
 

package/docs/probability.md

@@ -6,7 +6,7 @@ Use them for event timing and option weights, decision and mission scores, focus
 
 | Tool                        | Use                                                                                                                             |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `hoi4.probability_inspect`  | Discover weighted blocks, adapters, candidates, provenance, capabilities, and unsupported constructs.                           |
+| `hoi4.probability_inspect`  | Discover weighted blocks, compatible adapters, candidates, provenance, capabilities, and unsupported constructs.                |
 | `hoi4.probability_evaluate` | Evaluate eligibility, modifier traces, raw values, proven probabilities, and MTTH horizon chances across scenarios.             |
 | `hoi4.probability_sweep`    | Sweep declared ranges and locate sensitivity changes, breakpoints, and rank reversals.                                          |
 | `hoi4.probability_simulate` | Sample declared distributions with a deterministic seed and confidence intervals.                                               |
@@ -16,6 +16,8 @@ Use them for event timing and option weights, decision and mission scores, focus
 
 All seven tools are read-only. Proposed source is parsed in memory and never written. When an installed game root is configured, evaluation fails closed unless `launcher-settings.json` identifies the supported HOI4 build and checksum. Results otherwise state that they target the adapter version without claiming local-game verification.
 
+Pass a source without an adapter when the surface type is not yet known. Inspection returns every compatible adapter, candidate counts, and example candidate IDs. If a requested adapter, identifier, or candidate pool does not match the source, inspection returns the same discovery result with an explanation and suggested adapter instead of `PROBABILITY_SURFACE_EMPTY`; evaluation, sweeps, and simulation remain strict and still reject an empty requested surface.
+
 ## Scenarios
 
 A scenario contains only state the caller is willing to declare. Missing values stay unresolved. Alternatives and ranges produce exact branches or bounds; probability distributions require `hoi4.probability_simulate`.

package/docs/setup.md

@@ -1,6 +1,6 @@
 # Setup
 
-HOI4 Agent Tools requires Node.js 22 or 24.
+HOI4 Agent Tools requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
 
 ## Install
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.3.13",
+  "version": "2.5.0",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "hoi4-map"
   ],
   "engines": {
-    "node": "^22.0.0 || ^24.0.0"
+    "node": "^22.19.0 || ^24.0.0"
   },
   "files": [
     "dist/",
@@ -95,19 +95,19 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@fontsource-variable/roboto": "5.2.10",
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@fontsource-variable/roboto": "5.3.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "express": "5.2.1",
     "fast-glob": "3.3.3",
     "fontkit": "2.0.4",
     "iconv-lite": "0.7.3",
-    "jose": "6.2.4",
+    "jose": "6.2.8",
     "sharp": "0.35.3",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@modelcontextprotocol/inspector": "1.0.0",
+    "@modelcontextprotocol/inspector": "2.1.0",
     "@types/express": "5.0.6",
     "@types/fontkit": "2.0.9",
     "@types/node": "22.20.1",
@@ -115,22 +115,23 @@
     "@vitest/coverage-v8": "4.1.10",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
-    "eslint": "10.7.0",
+    "eslint": "10.8.1",
     "fast-check": "4.9.0",
     "pixelmatch": "7.2.0",
     "prettier": "3.9.6",
-    "tsx": "4.23.1",
+    "tsx": "4.23.11",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.65.0",
+    "typescript-eslint": "8.66.0",
     "vitest": "4.1.10"
   },
   "overrides": {
-    "@hono/node-server": "2.0.11",
+    "@hono/node-server": "2.1.0",
     "brace-expansion": "5.0.9",
     "fast-uri": "3.1.5",
-    "hono": "4.13.0",
+    "hono": "4.13.1",
+    "nanoid": "3.3.18",
     "ip-address": "10.4.0",
-    "postcss": "8.5.23",
+    "postcss": "8.5.26",
     "shell-quote": "1.10.0"
   },
   "publishConfig": {

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.13/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/continuous-focus-palette.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.13/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/custom-weighted-pool.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.13/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/event-feature-manifest.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.13/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/event-feature-manifest.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-plan.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.13/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/focus-plan.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-planning-sidecar.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.13/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {