hoi4-agent-tools 2.8.11 → 3.0.1

package/dist/hoi4_agent_tools/technology/render.js

@@ -46,7 +46,7 @@ function technologyNode(graph, technologyId, placement) {
         kind: technology.kind,
         sourcePath: technology.source.path,
         sourceLine: technology.source.location.start.line,
-        layoutSize: technology.layoutSize,
+        layoutSize: placement?.layoutSize ?? technology.layoutSize,
         iconSprite: technology.icon.sprite,
         ...(placement === undefined ? {} : { placement }),
     };
@@ -61,6 +61,7 @@ function sortedUniqueNodes(values) {
 function viewSelection(graph, options) {
     const nodes = [];
     const edges = [];
+    let yearMarkers = [];
     let title;
     let sourceAccurate = false;
     if (options.view === 'summary') {
@@ -117,6 +118,7 @@ function viewSelection(graph, options) {
             .filter(({ from, to }) => selected.has(from) && selected.has(to))
             .map(({ id, from, to, kind }) => ({ id, from, to, kind })));
         sourceAccurate = true;
+        yearMarkers = graph.yearMarkers.filter(({ folderId }) => folderId === options.folderId);
     }
     else if (options.view === 'dependencies' || options.view === 'technology') {
         const ids = options.technologyId === undefined
@@ -407,6 +409,7 @@ function viewSelection(graph, options) {
     return {
         nodes: selectedNodes,
         edges: selectedEdges,
+        yearMarkers,
         sourceAccurate,
         title,
         payload: {
@@ -416,6 +419,7 @@ function viewSelection(graph, options) {
             generatedAnalysisLayout: !sourceAccurate,
             nodes: selectedNodes,
             edges: selectedEdges,
+            yearMarkers,
             graphRevision: graph.revision,
             analysisBoundary: graph.analysisBoundary,
         },
@@ -424,38 +428,61 @@ function viewSelection(graph, options) {
 function issueKey(issue) {
     return sha256Bytes(canonicalJson({ code: issue.code, details: issue.details })).slice(0, 20);
 }
-function layoutFolder(nodes) {
-    const dimensions = (node) => node.layoutSize === 'small'
-        ? { width: SMALL_NODE_WIDTH, height: SMALL_NODE_HEIGHT }
-        : { width: LARGE_NODE_WIDTH, height: LARGE_NODE_HEIGHT };
+function layoutFolder(nodes, yearMarkers) {
+    const dimensions = (node) => node.placement?.layoutWidth !== undefined && node.placement.layoutHeight !== undefined
+        ? { width: node.placement.layoutWidth, height: node.placement.layoutHeight }
+        : node.layoutSize === 'small'
+            ? { width: SMALL_NODE_WIDTH, height: SMALL_NODE_HEIGHT }
+            : { width: LARGE_NODE_WIDTH, height: LARGE_NODE_HEIGHT };
     const sourcePixel = nodes.filter(({ placement }) => placement?.pixelX !== undefined && placement.pixelY !== undefined);
     if (sourcePixel.length === nodes.length && sourcePixel.length > 0) {
-        const minimumX = Math.min(...sourcePixel.map(({ placement }) => placement.pixelX));
-        const minimumY = Math.min(...sourcePixel.map(({ placement }) => placement.pixelY));
-        return sourcePixel.map((node) => {
+        const sourceNodeX = (node) => node.placement.pixelX + (node.placement?.layoutOffsetX ?? 0);
+        const sourceNodeY = (node) => node.placement.pixelY + (node.placement?.layoutOffsetY ?? 0);
+        const minimumX = Math.min(...sourcePixel.map(sourceNodeX), ...yearMarkers.map(({ position }) => position.x));
+        const minimumY = Math.min(...sourcePixel.map(sourceNodeY), ...yearMarkers.map(({ position }) => position.y));
+        const positionedNodes = sourcePixel.map((node) => {
             const size = dimensions(node);
             return {
                 ...node,
-                x: PADDING + node.placement.pixelX - minimumX,
-                y: HEADER_HEIGHT + PADDING + node.placement.pixelY - minimumY,
+                x: PADDING + sourceNodeX(node) - minimumX,
+                y: HEADER_HEIGHT + PADDING + sourceNodeY(node) - minimumY,
                 ...size,
             };
         });
+        const positionedYearMarkers = yearMarkers.map((marker) => ({
+            ...marker,
+            x: PADDING + marker.position.x - minimumX,
+            y: HEADER_HEIGHT + PADDING + marker.position.y - minimumY,
+        }));
+        const xValues = yearMarkers.map(({ position }) => position.x);
+        const yValues = yearMarkers.map(({ position }) => position.y);
+        const xSpan = xValues.length === 0 ? 0 : Math.max(...xValues) - Math.min(...xValues);
+        const ySpan = yValues.length === 0 ? 0 : Math.max(...yValues) - Math.min(...yValues);
+        return {
+            nodes: positionedNodes,
+            yearMarkers: positionedYearMarkers,
+            ...(yearMarkers.length === 0
+                ? {}
+                : { yearAxis: xSpan >= ySpan ? 'horizontal' : 'vertical' }),
+        };
     }
     const branchRoots = [
         ...new Set(nodes.map(({ placement }) => placement?.branchRootId ?? '<unresolved>')),
     ].sort(compareCodeUnits);
     const lanes = new Map(branchRoots.map((id, index) => [id, index]));
-    return nodes.map((node, index) => {
-        const placement = node.placement;
-        const lane = lanes.get(placement?.branchRootId ?? '<unresolved>') ?? 0;
-        const size = dimensions(node);
-        const x = PADDING + lane * 680 + (placement?.x ?? index % 3) * (LARGE_NODE_WIDTH + GAP_X);
-        const y = HEADER_HEIGHT +
-            PADDING +
-            (placement?.y ?? Math.floor(index / 3)) * (LARGE_NODE_HEIGHT + GAP_Y);
-        return { ...node, x, y, ...size };
-    });
+    return {
+        nodes: nodes.map((node, index) => {
+            const placement = node.placement;
+            const lane = lanes.get(placement?.branchRootId ?? '<unresolved>') ?? 0;
+            const size = dimensions(node);
+            const x = PADDING + lane * 680 + (placement?.x ?? index % 3) * (LARGE_NODE_WIDTH + GAP_X);
+            const y = HEADER_HEIGHT +
+                PADDING +
+                (placement?.y ?? Math.floor(index / 3)) * (LARGE_NODE_HEIGHT + GAP_Y);
+            return { ...node, x, y, ...size };
+        }),
+        yearMarkers: [],
+    };
 }
 function layoutGenerated(nodes, edges) {
     const ids = new Set(nodes.map(({ id }) => id));
@@ -544,9 +571,9 @@ function colours(kind) {
         removed: { fill: '#4a2828', stroke: '#ef7d7d' },
     }[kind];
 }
-function svgFor(titleText, positioned, edges, sourceAccurate, iconDataUris) {
-    const maximumX = Math.max(PADDING + LARGE_NODE_WIDTH, ...positioned.map(({ x, width }) => x + width));
-    const maximumY = Math.max(HEADER_HEIGHT + LARGE_NODE_HEIGHT, ...positioned.map(({ y, height }) => y + height));
+function svgFor(titleText, positioned, edges, sourceAccurate, iconDataUris, yearMarkers, yearAxis) {
+    const maximumX = Math.max(PADDING + LARGE_NODE_WIDTH, ...positioned.map(({ x, width }) => x + width), ...yearMarkers.map(({ x }) => x + 70));
+    const maximumY = Math.max(HEADER_HEIGHT + LARGE_NODE_HEIGHT, ...positioned.map(({ y, height }) => y + height), ...yearMarkers.map(({ y }) => y + 30));
     const width = Math.ceil(maximumX + PADDING);
     const height = Math.ceil(maximumY + PADDING);
     if (width > 16_384 || height > 16_384 || width * height > RENDER_MAX_PIXELS)
@@ -556,6 +583,19 @@ function svgFor(titleText, positioned, edges, sourceAccurate, iconDataUris) {
         });
     const byId = new Map(positioned.map((node) => [node.id, node]));
     const text = new DeterministicSvgTextRenderer();
+    const yearGuideSvg = yearMarkers.map((marker) => {
+        const guide = yearAxis === 'vertical'
+            ? `<line x1="${PADDING}" y1="${marker.y + 15}" x2="${width - PADDING}" y2="${marker.y + 15}" stroke="#34495c" stroke-width="1" stroke-dasharray="5 7"/>`
+            : `<line x1="${marker.x + 24}" y1="${HEADER_HEIGHT}" x2="${marker.x + 24}" y2="${height - PADDING}" stroke="#34495c" stroke-width="1" stroke-dasharray="5 7"/>`;
+        const label = text.render(String(marker.year), {
+            x: marker.x,
+            y: marker.y + 22,
+            fontSize: 18,
+            fill: '#c7d4df',
+            weight: 700,
+        });
+        return `<g data-tech-year="${marker.year}" data-year-axis="${yearAxis ?? 'horizontal'}" data-source-path="${escapeXml(marker.sourcePath)}" data-source-line="${marker.location.start.line}">${guide}${label}</g>`;
+    });
     const edgeSvg = edges.flatMap((edge) => {
         const from = byId.get(edge.from);
         const to = byId.get(edge.to);
@@ -624,7 +664,7 @@ function svgFor(titleText, positioned, edges, sourceAccurate, iconDataUris) {
     return {
         width,
         height,
-        svg: `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeXml(titleText)}"><defs><marker id="tech-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#8298ad"/></marker>${text.definitions()}</defs><rect width="100%" height="100%" fill="#0d1721"/>${title}${mode}<g>${edgeSvg.join('')}</g><g>${nodeSvg.join('')}</g></svg>`,
+        svg: `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeXml(titleText)}"><defs><marker id="tech-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#8298ad"/></marker>${text.definitions()}</defs><rect width="100%" height="100%" fill="#0d1721"/>${title}${mode}<g>${yearGuideSvg.join('')}</g><g>${edgeSvg.join('')}</g><g>${nodeSvg.join('')}</g></svg>`,
     };
 }
 function htmlFor(title, svg, json) {
@@ -637,16 +677,17 @@ export async function renderTechnologyGraph(graph, options) {
     const retained = selection.nodes.slice(0, maximum);
     const retainedIds = new Set(retained.map(({ id }) => id));
     const edges = selection.edges.filter(({ from, to }) => retainedIds.has(from) && retainedIds.has(to));
-    const positioned = selection.sourceAccurate
-        ? layoutFolder(retained)
-        : layoutGenerated(retained, edges);
+    const folderLayout = selection.sourceAccurate
+        ? layoutFolder(retained, selection.yearMarkers)
+        : { nodes: layoutGenerated(retained, edges), yearMarkers: [] };
+    const positioned = folderLayout.nodes;
     const iconDataUris = options.iconDataUris ?? {};
     const requestedIconSprites = [
         ...new Set(retained.flatMap(({ iconSprite }) => (iconSprite === undefined ? [] : [iconSprite]))),
     ].sort(compareCodeUnits);
     const renderedIconSprites = requestedIconSprites.filter((sprite) => iconDataUris[sprite] !== undefined);
     const unresolvedIconSprites = requestedIconSprites.filter((sprite) => iconDataUris[sprite] === undefined);
-    const rendered = svgFor(selection.title, positioned, edges, selection.sourceAccurate, iconDataUris);
+    const rendered = svgFor(selection.title, positioned, edges, selection.sourceAccurate, iconDataUris, folderLayout.yearMarkers, folderLayout.yearAxis);
     const budget = options.budget ?? new RenderBudget();
     budget.reserve(rendered.width, rendered.height, `technology ${options.view} render`);
     budget.reserveRasterOperation(`technology-render:${graph.revision}:${options.view}:${sha256Bytes(rendered.svg)}`, `technology ${options.view} rasterization`);
@@ -667,6 +708,10 @@ export async function renderTechnologyGraph(graph, options) {
             unresolvedSprites: unresolvedIconSprites,
         },
         render: { width: rendered.width, height: rendered.height },
+        yearGuide: {
+            axis: folderLayout.yearAxis ?? null,
+            markerCount: folderLayout.yearMarkers.length,
+        },
     })}\n`;
     const html = options.includeHtml === true ? htmlFor(selection.title, rendered.svg, json) : undefined;
     return {

package/dist/hoi4_agent_tools/technology/service.js

@@ -10,6 +10,7 @@ import { GuiAssetCatalog } from '../gui/assets.js';
 import { buildGuiSourceGraph } from '../gui/source-graph.js';
 import { compareTechnologyGraphs } from './compare.js';
 import { buildTechnologyGraph, technologyAssetPatterns } from './graph.js';
+import { TECHNOLOGY_GRAPH_SCHEMA_VERSION } from './model.js';
 import { analyzeTechnologyImpact, discoverTechnologyFolders, explainTechnology, inspectTechnologyUnlocks, lintTechnologyGraph, technologyBonusCoverage, technologyScanReport, traceTechnology, } from './queries.js';
 import { renderTechnologyGraph, technologyRenderIconSprites, } from './render.js';
 const FRAGMENT_CACHE_ENTRIES = 8_192;
@@ -293,13 +294,15 @@ function validateGraph(value) {
         throw new ServiceError('TECH_GRAPH_ARTIFACT_INVALID', 'Technology graph artifact is not an object');
     const graph = value;
     const sourceHashes = value.sourceHashes;
-    if (graph.schemaVersion !== 1 ||
+    if (graph.schemaVersion !== TECHNOLOGY_GRAPH_SCHEMA_VERSION ||
         typeof graph.workspaceId !== 'string' ||
         typeof graph.workspaceIdentity !== 'string' ||
         typeof graph.revision !== 'string' ||
         !Array.isArray(graph.technologies) ||
         !Array.isArray(graph.edges) ||
         !Array.isArray(graph.placements) ||
+        !Array.isArray(graph.itemLayouts) ||
+        !Array.isArray(graph.yearMarkers) ||
         sourceHashes === null ||
         typeof sourceHashes !== 'object')
         throw new ServiceError('TECH_GRAPH_ARTIFACT_INVALID', 'Technology graph artifact has an invalid schema');

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

@@ -350,11 +350,7 @@ function parseTechnologyDefinitions(file, document, fragment) {
             ].sort(compareCodeUnits);
             const layoutExpression = firstValue(block, 'force_use_small_tech_layout');
             const smallLayout = booleanValue(layoutExpression);
-            const layoutSize = layoutExpression === undefined || smallLayout === false
-                ? 'large'
-                : smallLayout === true
-                    ? 'small'
-                    : 'unknown';
+            const layoutSize = smallLayout === true ? 'small' : 'unknown';
             const unsupportedFields = fragment.placements
                 .filter(({ technologyId, xExpression, yExpression }) => technologyId === id && (xExpression !== undefined || yExpression !== undefined))
                 .map((placement) => ({
@@ -581,12 +577,22 @@ function parseModernDoctrines(file, document, fragment) {
         }
     }
 }
+function technologyFolderContainer(namedContainers) {
+    return [...namedContainers].reverse().find((name) => /_folder(?:_|$)/iu.test(name));
+}
+function technologyItemLayoutName(name) {
+    const small = /^techtree_(.+)_small_item$/iu.exec(name);
+    if (small?.[1] !== undefined)
+        return { folderId: small[1], layoutSize: 'small' };
+    const large = /^techtree_(.+)_item$/iu.exec(name);
+    if (large?.[1] !== undefined)
+        return { folderId: large[1], layoutSize: 'large' };
+    return undefined;
+}
 function parseTechnologyGridboxes(file, document, fragment, signal) {
     if (!normalizedPath(file).endsWith('.gui'))
         return;
-    const stack = [
-        { block: document.root, namedContainers: [] },
-    ];
+    const stack = [{ block: document.root, namedContainers: [], offsetX: 0, offsetY: 0 }];
     let visited = 0;
     while (stack.length > 0) {
         if (visited % 128 === 0)
@@ -599,11 +605,14 @@ function parseTechnologyGridboxes(file, document, fragment, signal) {
             const block = assignment.value;
             const elementType = assignment.key.value.toLowerCase();
             const name = firstScalar(block, 'name');
+            const position = childBlocks(block, 'position')[0];
+            const localX = numericLiteral(position === undefined ? undefined : firstValue(position, 'x'));
+            const localY = numericLiteral(position === undefined ? undefined : firstValue(position, 'y'));
+            const absoluteX = current.offsetX + (localX ?? 0);
+            const absoluteY = current.offsetY + (localY ?? 0);
+            const folderId = technologyFolderContainer(current.namedContainers);
             if (elementType === 'gridboxtype' && name?.value.endsWith('_tree') === true) {
-                const position = childBlocks(block, 'position')[0];
                 const slotSize = childBlocks(block, 'slotsize')[0];
-                const x = numericLiteral(position === undefined ? undefined : firstValue(position, 'x'));
-                const y = numericLiteral(position === undefined ? undefined : firstValue(position, 'y'));
                 const width = numericLiteral(slotSize === undefined ? undefined : firstValue(slotSize, 'width'));
                 const height = numericLiteral(slotSize === undefined ? undefined : firstValue(slotSize, 'height'));
                 const gridbox = {
@@ -613,16 +622,14 @@ function parseTechnologyGridboxes(file, document, fragment, signal) {
                         offset: assignment.start,
                     }),
                     name: name.value,
-                    ...(current.namedContainers.at(-1) === undefined
-                        ? {}
-                        : { folderId: current.namedContainers.at(-1) }),
+                    ...(folderId === undefined ? {} : { folderId }),
                     position: {
-                        ...(x === undefined ? {} : { x }),
-                        ...(y === undefined ? {} : { y }),
-                        ...(position === undefined || x !== undefined
+                        ...(localX === undefined ? {} : { x: absoluteX }),
+                        ...(localY === undefined ? {} : { y: absoluteY }),
+                        ...(position === undefined || localX !== undefined
                             ? {}
                             : { xExpression: firstValue(position, 'x') ?? '<missing>' }),
-                        ...(position === undefined || y !== undefined
+                        ...(position === undefined || localY !== undefined
                             ? {}
                             : { yExpression: firstValue(position, 'y') ?? '<missing>' }),
                     },
@@ -645,11 +652,85 @@ function parseTechnologyGridboxes(file, document, fragment, signal) {
                 };
                 fragment.gridboxes.push(gridbox);
             }
+            if (elementType === 'containerwindowtype' && name !== undefined) {
+                const item = technologyItemLayoutName(name.value);
+                if (item !== undefined) {
+                    const size = childBlocks(block, 'size')[0];
+                    const width = numericLiteral(size === undefined ? undefined : firstValue(size, 'width'));
+                    const height = numericLiteral(size === undefined ? undefined : firstValue(size, 'height'));
+                    const layout = {
+                        id: deterministicId('tech-item-layout', {
+                            name: name.value,
+                            path: file.displayPath,
+                            offset: assignment.start,
+                        }),
+                        name: name.value,
+                        folderId: item.folderId,
+                        layoutSize: item.layoutSize,
+                        position: {
+                            ...(localX === undefined ? {} : { x: localX }),
+                            ...(localY === undefined ? {} : { y: localY }),
+                            ...(position === undefined || localX !== undefined
+                                ? {}
+                                : { xExpression: firstValue(position, 'x') ?? '<missing>' }),
+                            ...(position === undefined || localY !== undefined
+                                ? {}
+                                : { yExpression: firstValue(position, 'y') ?? '<missing>' }),
+                        },
+                        size: {
+                            ...(width === undefined ? {} : { width }),
+                            ...(height === undefined ? {} : { height }),
+                            ...(size === undefined || width !== undefined
+                                ? {}
+                                : { widthExpression: firstValue(size, 'width') ?? '<missing>' }),
+                            ...(size === undefined || height !== undefined
+                                ? {}
+                                : { heightExpression: firstValue(size, 'height') ?? '<missing>' }),
+                        },
+                        location: nodeLocation(document, assignment, name.value),
+                        sourcePath: file.displayPath,
+                        loadOrder: file.loadOrder,
+                    };
+                    fragment.itemLayouts.push(layout);
+                }
+            }
+            if (elementType === 'instanttextboxtype' && name !== undefined && folderId !== undefined) {
+                const text = firstValue(block, 'text');
+                const year = text === undefined
+                    ? undefined
+                    : /^(?:18|19|20)\d{2}$/u.test(text)
+                        ? Number(text)
+                        : undefined;
+                if (year !== undefined && localX !== undefined && localY !== undefined) {
+                    const marker = {
+                        id: deterministicId('tech-year-marker', {
+                            name: name.value,
+                            year,
+                            path: file.displayPath,
+                            offset: assignment.start,
+                        }),
+                        name: name.value,
+                        folderId,
+                        year,
+                        position: { x: absoluteX, y: absoluteY },
+                        location: nodeLocation(document, assignment, name.value),
+                        sourcePath: file.displayPath,
+                        loadOrder: file.loadOrder,
+                    };
+                    fragment.yearMarkers.push(marker);
+                }
+            }
             const namedContainers = name !== undefined &&
                 (elementType === 'containerwindowtype' || elementType === 'windowtype')
                 ? [...current.namedContainers, name.value]
                 : current.namedContainers;
-            stack.push({ block, namedContainers });
+            const positionedContainer = elementType === 'containerwindowtype' || elementType === 'windowtype';
+            stack.push({
+                block,
+                namedContainers,
+                offsetX: positionedContainer ? absoluteX : current.offsetX,
+                offsetY: positionedContainer ? absoluteY : current.offsetY,
+            });
         }
     }
 }
@@ -913,6 +994,8 @@ export function analyzeTechnologySource(file, context) {
         folders: [],
         placements: [],
         gridboxes: [],
+        itemLayouts: [],
+        yearMarkers: [],
         edges: [],
         categories: [],
         doctrineDefinitions: [],

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.8.11';
+export const PACKAGE_VERSION = '3.0.1';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/development.md

@@ -35,4 +35,6 @@ npm run test:local
 
 Add `HOI4_DEPENDENCY_ROOTS` as the platform path-delimited list when the external mod has dependencies. Local tests remain read-only.
 
+The installed-game qualification also parses every shipped bitmap-font descriptor, resolves every atlas page, shapes native and enlarged glyphs, verifies deterministic raster output, and checks HOI4 localisation colours across base fonts and language overrides.
+
 See the package [Security Policy](../SECURITY.md) for private vulnerability reporting.

package/docs/gui.md

@@ -31,13 +31,13 @@ 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.
 
-The renderer resolves sprites and fonts through the complete mod, dependency, and installed-game load order. Mod windows therefore render ordinary vanilla sprites, tiled vanilla panels, progress bars, masked shields, button frames, and localisation icons such as `£command_power` without copying game assets into the mod. Case differences in GFX and font identifiers do not prevent a valid asset from resolving.
+The renderer resolves sprites and fonts through the complete mod, dependency, and installed-game load order. Mod windows therefore render ordinary vanilla sprites, tiled vanilla panels, progress bars, masked shields, button frames, country flags, and localisation icons such as `£command_power` without copying game assets into the mod. Case differences in GFX and font identifiers do not prevent a valid asset from resolving.
 
 Bitmap text uses the language-appropriate HOI4 font definition and its real glyph atlas. Header, serif, compact, typewriter, black, inverted, and other declared faces keep their own glyph shapes, native metrics, face colour, border colour, language override, and font-specific `textcolors` palette. The renderer reads BMFont channel roles, separates face and outline coverage, and recognizes both vanilla black-on-white masks and conventional white-on-transparent custom masks. HOI4 localisation colour runs such as `§Y` and `§R` therefore colour the glyph face while retaining its sharp antialiasing and declared border instead of flattening the glyph into a blurred monochrome mask or switching to the tool font. The default language uses the base font rather than an unrelated language override, and the renderer recognizes installed-game atlases whose filename omits a page suffix declared by the matching `.fnt` file.
 
 Layout follows Clausewitz orientation and element-origin anchors, including `CENTER_LEFT`, `CENTER_RIGHT`, `CENTER_UP`, `CENTER_DOWN`, `origo`, `centerposition`, inherited container coordinate origins, local scale, and both `%` and `%%` relative dimensions. Text boxes use native font metrics together with `maxWidth`, `maxHeight`, alignment, wrapping, and `fixedsize` clipping. Cornered tile sprites use fixed nine-slice borders and optional center tiling; progress bars composite their filled and background textures; masked shields composite their background and mask textures.
 
-Scripted-GUI composition follows `parent_scripted_gui` chains even when the linked child window is a top-level sibling in the `.gui` file. Literal `always = yes` and `always = no` visibility and click-enabled blocks are applied automatically. A scenario's `values` object supplies concrete runtime values in one place: variable names resolve numeric text, scripted-localisation names resolve dynamic labels, a progress-bar element name sets its fill value, and element keys ending in `.image`, `.frame`, `.x`, `.y`, `.visible`, or `.enabled` update that visual property. Scripted-GUI property expressions such as `image = "[GetMeterSprite]"` or `x = meter_fill_width` consume matching scenario values automatically. Dynamic lists instantiate their declared `entry_container` or `country_scope_entry_container`; each scenario row can select the country template with `countryScope`, choose an explicit `entryContainer`, and provide row-scoped text, image, frame, position, visibility, and enabled values.
+Scripted-GUI composition follows `parent_scripted_gui` chains even when the linked child window is a top-level sibling in the `.gui` file. Literal `always = yes` and `always = no` visibility and click-enabled blocks are applied automatically. A scenario's `values` object supplies concrete runtime values in one place: variable names resolve numeric text, scripted-localisation names resolve dynamic labels, a progress-bar element name sets its fill value, and element keys ending in `.image`, `.frame`, `.x`, `.y`, `.visible`, or `.enabled` update that visual property. Scripted-GUI property expressions such as `image = "[GetMeterSprite]"` or `x = meter_fill_width` consume matching scenario values automatically. Dynamic text is parsed after scenario and scripted-localisation substitution, so a runtime string containing `£command_power` or `£[GetResourceIcon]` renders the resolved inline HOI4 text icon instead of literal marker text. Dynamic lists instantiate their declared `entry_container` or `country_scope_entry_container`; each scenario row can select the country template with `countryScope`, choose an explicit `entryContainer`, provide `countryTag` and `ideology` for `GetFlag`, and supply row-scoped text, image, frame, position, visibility, and enabled values. Masked country sprites use the actual mask and overlay dimensions, so custom flag sizes are discovered from GFX assets rather than assumed by the renderer.
 
 `hoi4.gui_inspect` and `hoi4.gui_render` generate a plausible seeded runtime scenario by default. The generator follows the complete `parent_scripted_gui` surface, discovers numeric and text tokens in GUI localisation and scripted-GUI properties, chooses real scripted-localisation text and sprite candidates, applies simple source thresholds, fills meters within their declared ranges, populates dynamic lists with coherent rows, selects one overlapping tab pane, keeps active and idle controls mutually exclusive, and leaves values explicitly supplied by the caller unchanged. Normal controls and animation frames remain stable unless variation is explicitly requested. Every explicit `relatedScenarios` entry is rendered beside the generated view.
 
@@ -66,11 +66,22 @@ Preview scenarios can include exact layout expectations:
   "values": {
     "threat": 73,
     "GetThreatLabel": "High",
+    "GetCostLine": "Cost £command_power 20",
     "threat_meter": 73,
     "confirm_button.enabled": true
   },
   "flags": { "panel_open": true },
-  "lists": { "target_list": [{ "id": 1, "label": "First target" }] },
+  "lists": {
+    "target_list": [
+      {
+        "id": 1,
+        "label": "France",
+        "countryScope": true,
+        "countryTag": "FRA",
+        "ideology": "democratic"
+      }
+    ]
+  },
   "visibility": { "target_list": true, "confirm_button": true },
   "expectations": {
     "visible": ["target_list", "confirm_button"],

package/docs/probability.md

@@ -16,7 +16,9 @@ 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.
+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, sweep, simulation, and source comparison also accept an omitted adapter. When a source selector identifies one unambiguous weighted surface, the analyzer selects that source-backed adapter automatically. If a caller supplies a mismatched adapter or `custom_weighted_pool` for a source-backed request, the analyzer corrects it when the source has exactly one match. `customPoolManifest`, `beforeManifest`, and `afterManifest` use the custom-pool adapter automatically; `PROBABILITY_SURFACE_EMPTY` is reserved for sources with no weighted surface, while genuinely multi-adapter sources ask the caller to narrow by identifier or line.
 
 ## Scenarios
 

package/docs/technology.md

@@ -49,7 +49,7 @@ Game-backed and otherwise large workspaces automatically use focused analysis mo
 
 ## Render
 
-`hoi4.tech_render` returns authoritative JSON with deterministic SVG and PNG resources; set `includeHtml` when a bundled static report is useful. Available views are `summary`, `folder`, `dependencies`, `technology`, `doctrine`, `exclusive`, `memberships`, `bonuses`, `grants`, `unlocks`, `metadata`, `assets`, and `unresolved`.
+`hoi4.tech_render` returns authoritative JSON with deterministic SVG and PNG resources; set `includeHtml` when a bundled static report is useful. Folder renders read the actual `techtree_<folder>_item` and `techtree_<folder>_small_item` geometry, choose the small item for technologies that do not unlock equipment or explicitly force it, and include the source GUI's horizontal or vertical year guide. Available views are `summary`, `folder`, `dependencies`, `technology`, `doctrine`, `exclusive`, `memberships`, `bonuses`, `grants`, `unlocks`, `metadata`, `assets`, and `unresolved`.
 
 Folder renders use the actual folder assignments, gridbox geometry, technology coordinates, and HOI4 item size found in source. Technologies with `force_use_small_tech_layout = yes` render as compact icon items; normal technologies render as large items with their icon and label. Sprite declarations and texture files resolve through the active load order across the mod, configured dependencies, and the detected or configured game installation, so vanilla icons used by a mod appear in SVG, PNG, and HTML artifacts. The authoritative JSON and SVG expose `layoutSize`, rendered-icon coverage, and unresolved sprite names without embedding image data in JSON. Dependency and other semantic views are explicitly labelled as generated analysis layouts.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.8.11",
+  "version": "3.0.1",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,6 +47,7 @@
     "docs/map.md",
     "docs/http.md",
     "docs/development.md",
+    "docs/images/readme/",
     "examples/clients/",
     "examples/probability/",
     "schemas/",
@@ -75,6 +76,7 @@
     "test:local": "tsx scripts/run-local-tests.ts",
     "test:coverage": "vitest run --coverage",
     "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
+    "docs:examples": "tsx scripts/generate-readme-examples.ts",
     "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event && npm run fixtures:generate:technology && npm run fixtures:generate:probability",
     "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
     "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.1/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
@@ -60,13 +60,13 @@
       "minLength": 1
     },
     "__schema2": {
-      "default": 20000,
+      "default": 100000,
       "type": "integer",
       "minimum": 1,
       "maximum": 1000000
     },
     "__schema3": {
-      "default": 134217728,
+      "default": 268435456,
       "type": "integer",
       "minimum": 1048576,
       "maximum": 9007199254740991

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

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.1/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.8.11/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.1/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.8.11/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.1/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.8.11/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.1/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.8.11/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.1/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-animation-source.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.1/schemas/gui-animation-source.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-helper.schema.json

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