hoi4-agent-tools 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 3.4.0 - 2026-09-20
+
+- Add branch-local focus cleanup with pinned anchors and symmetry groups, connector measurements, source-linked crops, and scenario-backed structural route diagnostics.
+- Report GUI visibility and enabled branches, measured label and background boxes, and matched source-baseline renders alongside scenario comparisons.
+- Expose complete source-backed probability catalogs, actionable missing scenario inputs, and eligible, excluded, and unresolved inventories.
+- Add selected event-chain comparisons and revision-bound bounded helper expansion while retaining explicit lifecycle coverage limits.
+- Compose technology folders from source pixel placements, native item skins, icon and subtechnology positions, panel and background artwork, year labels, and supplied research scenarios; report unresolved placement and asset coverage honestly.
+- Resolve source `GFX_*_medium` artwork and design-team overlays at native item size for chemical and biological warfare folders.
+- Compose installed GUI backgrounds, focus inlays, container scrolling, native button and progress shaders, and scenario-driven rows from source assets and control states.
+- Bound focus connector and overlap diagnostics on anchored trees with thousands of nodes.
+- Add focused map lookups, reusable render tiles, affected-area output, and typed external script-reference updates for map renumbering.
+
 ## 3.3.0 - 2026-09-20
 
 - Add `hoi4.mechanic_test` with copied versioned scenario state, bounded source effects, explicit time advancement, traces, and typed gameplay assertions.

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

@@ -96,7 +96,7 @@ function numberValue(expression, scenario, context, definitions, path, seen = ne
     }
     return undefined;
 }
-function unresolved(assignment, candidate, reason) {
+function unresolved(assignment, candidate, reason, scenarioInput) {
     return {
         state: 'unresolved',
         unresolved: [
@@ -104,6 +104,7 @@ function unresolved(assignment, candidate, reason) {
                 code: 'TRIGGER_UNRESOLVED',
                 message: reason,
                 path: assignment.key.value,
+                ...(scenarioInput === undefined ? {} : { details: { scenarioInput } }),
                 candidateId: candidate.id,
                 ...(candidate.provenance[0] === undefined ? {} : { provenance: candidate.provenance[0] }),
             },
@@ -136,7 +137,11 @@ function evaluateCheckVariable(block, scenario, candidate, assignment, scopeCont
     const leftNumber = numberValue(variable, scenario, scopeContext, definitions, path);
     const rightNumber = numberValue(target, scenario, scopeContext, definitions, path);
     if (leftNumber === undefined || rightNumber === undefined)
-        return unresolved(assignment, candidate, `Scenario does not resolve numeric operands ${variable} and ${target}`);
+        return unresolved(assignment, candidate, `Scenario does not resolve numeric operands ${variable} and ${target}`, leftNumber === undefined && !/^(?:@|constant:)/u.test(variable)
+            ? `variable.${variable}`
+            : rightNumber === undefined && !/^(?:@|constant:)/u.test(target)
+                ? `variable.${target}`
+                : undefined);
     const compareName = firstScalar(block, 'compare')?.value ??
         (short?.operator.text === '>'
             ? 'greater_than'
@@ -202,7 +207,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             const array = scopeStateValue(scenario, `array.${arrayId}`, scopeContext) ??
                 rootStateValue(scenario, `array.${arrayId}`);
             if (!Array.isArray(array))
-                return unresolved(assignment, candidate, `Scenario does not declare array ${arrayId}`);
+                return unresolved(assignment, candidate, `Scenario does not declare array ${arrayId}`, `array.${arrayId}`);
             const compared = ['THIS', 'ROOT', 'PREV'].includes(declaredValue.toUpperCase()) ||
                 resolveScopeContext(scenario, declaredValue, scopeContext) !== undefined
                 ? scopeIdentity(resolveScopeContext(scenario, declaredValue, scopeContext) ?? scopeContext)
@@ -244,7 +249,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
         const declaredScope = bool(rootStateValue(scenario, `scope.${key}`));
         if (declaredScope !== undefined)
             return { state: declaredScope ? 'true' : 'false', unresolved: [] };
-        return unresolved(assignment, candidate, `Scoped or compound trigger ${key} is not declared by the scenario`);
+        return unresolved(assignment, candidate, `Scoped or compound trigger ${key} is not declared by the scenario`, `scope.${key}`);
     }
     const right = assignment.value.value;
     if (key === 'always') {
@@ -263,7 +268,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
                 ? scenario.flags
                 : scopeContext.binding.flags;
         if (scenario.closedFlags === false && flags?.includes(right) !== true)
-            return unresolved(assignment, candidate, `Scenario does not declare flag ${right}`);
+            return unresolved(assignment, candidate, `Scenario does not declare flag ${right}`, `flag.${right}`);
         return { state: flags?.includes(right) === true ? 'true' : 'false', unresolved: [] };
     }
     if (key === 'has_event_target') {
@@ -278,7 +283,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             ? scenario.actor
             : (scopeContext.binding.actor ?? scopeContext.binding.id);
         if (actor === undefined)
-            return unresolved(assignment, candidate, `Scenario does not declare actor for ${key}`);
+            return unresolved(assignment, candidate, `Scenario does not declare actor for ${key}`, 'actor');
         return {
             state: compare(actor, right, assignment.operator.text) ? 'true' : 'false',
             unresolved: [],
@@ -286,7 +291,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
     }
     if (key === 'date') {
         if (scenario.date === undefined)
-            return unresolved(assignment, candidate, 'Scenario does not declare date');
+            return unresolved(assignment, candidate, 'Scenario does not declare date', 'date');
         const dateNumber = (value) => {
             const parts = /^(\d+)\.(\d{1,2})\.(\d{1,2})$/u.exec(value);
             if (parts === null)
@@ -336,7 +341,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
     const declared = scopeStateValue(scenario, key, scopeContext) ??
         numberValue(key, scenario, scopeContext, definitions, candidate.provenance[0]?.path);
     if (declared === undefined)
-        return unresolved(assignment, candidate, `Scenario does not declare trigger ${key}`);
+        return unresolved(assignment, candidate, `Scenario does not declare trigger ${key}`, key);
     const expectedBoolean = bool(right);
     const actualBoolean = bool(declared);
     if (expectedBoolean !== undefined && actualBoolean !== undefined)

package/dist/hoi4_agent_tools/core/helper-expansion.js

@@ -104,6 +104,9 @@ export async function inspectHelperExpansion(engine, workspaceId, inventory, req
         kind,
         rootId: input.roots[root],
         path: path.map((index) => inventory.edges[index].id),
+        ...(inventory.recordDetails === undefined
+            ? {}
+            : inventory.recordDetails(path.map((index) => inventory.edges[index]))),
     }));
     const continuationName = `${inventory.domain}-helper-continuation.json`;
     const report = {

package/dist/hoi4_agent_tools/event/comparison-selection.js

@@ -0,0 +1,78 @@
+import { compareCodeUnits } from '../core/canonical.js';
+import { traceEventGraph } from './algorithms.js';
+import { selectEventNodes } from './queries.js';
+/** Project a whole-graph comparison onto the downstream chain in each revision. */
+export function selectEventComparison(before, after, comparison, selector, maxChainNodes, signal) {
+    const trace = (graph) => {
+        const starts = selectEventNodes(graph, selector, signal).map(({ id }) => id);
+        return traceEventGraph(graph, starts, {
+            maxDepth: 64,
+            maxNodes: maxChainNodes,
+            maxEdges: Math.max(1, Math.min(20_000, graph.edges.length)),
+            direction: 'downstream',
+            expandHelpers: true,
+        }, signal);
+    };
+    const beforeTrace = trace(before);
+    const afterTrace = trace(after);
+    const beforeNodeIds = beforeTrace.nodes.map(({ id }) => id).sort(compareCodeUnits);
+    const afterNodeIds = afterTrace.nodes.map(({ id }) => id).sort(compareCodeUnits);
+    const selectedNodes = new Set([...beforeNodeIds, ...afterNodeIds]);
+    const edges = new Map([...before.edges, ...after.edges].map((edge) => [edge.id, edge]));
+    const accesses = new Map([...before.stateAccesses, ...after.stateAccesses].map((access) => [access.id, access]));
+    const links = new Map([...before.stateLinks, ...after.stateLinks].map((link) => [link.id, link]));
+    const unresolved = new Map([...before.unresolved, ...after.unresolved].map((item) => [item.id, item]));
+    const association = (change) => {
+        const { kind, subjectId } = change;
+        if (kind.startsWith('node_') || kind === 'caller_removed' || kind.endsWith('_disconnected'))
+            return selectedNodes.has(subjectId);
+        if (kind.startsWith('edge_')) {
+            const edge = edges.get(subjectId);
+            return edge === undefined
+                ? undefined
+                : selectedNodes.has(edge.from) || selectedNodes.has(edge.to);
+        }
+        if (kind.startsWith('state_access_')) {
+            const access = accesses.get(subjectId);
+            return access === undefined ? undefined : selectedNodes.has(access.ownerId);
+        }
+        if (kind.startsWith('state_link_')) {
+            const link = links.get(subjectId);
+            if (link === undefined)
+                return undefined;
+            const producer = accesses.get(link.producerId);
+            const consumer = accesses.get(link.consumerId);
+            return producer === undefined && consumer === undefined
+                ? undefined
+                : (producer !== undefined && selectedNodes.has(producer.ownerId)) ||
+                    (consumer !== undefined && selectedNodes.has(consumer.ownerId));
+        }
+        if (kind.startsWith('unresolved_')) {
+            const item = unresolved.get(subjectId);
+            return item?.ownerId === undefined ? undefined : selectedNodes.has(item.ownerId);
+        }
+        return undefined;
+    };
+    const selectedChangeIds = [];
+    const unattributedChangeIds = [];
+    for (const [index, change] of comparison.changes.entries()) {
+        if ((index & 255) === 0)
+            signal?.throwIfAborted();
+        const relevant = association(change);
+        if (relevant === true)
+            selectedChangeIds.push(change.id);
+        else if (relevant === undefined)
+            unattributedChangeIds.push(change.id);
+    }
+    return {
+        selector,
+        maxChainNodes,
+        beforeNodeIds,
+        afterNodeIds,
+        selectedChangeIds,
+        selectedChangeCount: selectedChangeIds.length,
+        omittedChangeCount: comparison.changes.length - selectedChangeIds.length,
+        unattributedChangeIds,
+        truncated: beforeTrace.truncated || afterTrace.truncated,
+    };
+}

package/dist/hoi4_agent_tools/event/helper-expansion.js

@@ -2,6 +2,14 @@ import { compareCodeUnits } from '../core/canonical.js';
 export function eventHelperInventory(graph) {
     const helpers = new Set(graph.nodes.filter(({ kind }) => kind === 'helper').map(({ id }) => id));
     const structural = graph.edges.filter(({ derived }) => !derived);
+    const structuralById = new Map(structural.map((edge) => [edge.id, edge]));
+    const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+    const optionParents = new Map(graph.edges
+        .filter(({ reason }) => reason === 'option_branch')
+        .map(({ from, to }) => [to, from]));
+    const accessById = new Map(graph.stateAccesses
+        .filter(({ ownerId }) => helpers.has(ownerId))
+        .map((access) => [`state-access:${access.id}`, access]));
     return {
         domain: 'event',
         sourceRevision: graph.revision,
@@ -29,5 +37,45 @@ export function eventHelperInventory(graph) {
             .map(({ id }) => id)
             .sort(compareCodeUnits),
         branches: [...helpers].sort(compareCodeUnits),
+        recordDetails: (path) => {
+            let current = 'unknown';
+            const root = structuralById.get(path[0]?.id ?? '');
+            if (root !== undefined) {
+                const caller = nodesById.get(optionParents.get(root.from) ?? root.from);
+                const candidate = root.scope?.source ?? caller?.metadata.expectedScope ?? caller?.metadata.scope;
+                if (candidate === 'country' ||
+                    candidate === 'state' ||
+                    candidate === 'province' ||
+                    candidate === 'unit_leader' ||
+                    candidate === 'operative' ||
+                    candidate === 'character' ||
+                    candidate === 'global')
+                    current = candidate;
+            }
+            const transitions = [];
+            for (const { id } of path) {
+                const edge = structuralById.get(id);
+                if (edge?.scope !== undefined) {
+                    const { source, destination, confidence } = edge.scope;
+                    current =
+                        current !== 'unknown' && source !== 'unknown' && current !== source
+                            ? 'unknown'
+                            : destination;
+                    transitions.push({ edgeId: id, source, destination: current, confidence });
+                }
+                const access = accessById.get(id);
+                if (access !== undefined) {
+                    return {
+                        scopeEvidence: {
+                            stateAccessId: access.id,
+                            declaredScope: access.scope,
+                            resolvedScope: access.scope === 'unknown' ? current : access.scope,
+                            transitions,
+                        },
+                    };
+                }
+            }
+            return { scopeEvidence: { resolvedScope: current, transitions } };
+        },
     };
 }

package/dist/hoi4_agent_tools/event/operations.js

@@ -130,6 +130,15 @@ export async function compareEvents(viewer, input) {
         ...(compared.render === undefined ? {} : { renderHashes: compared.render.hashes }),
         counts: {
             changes: comparison.changes.length,
+            ...(compared.selection === undefined
+                ? {}
+                : {
+                    selectedChanges: compared.selection.selectedChangeCount,
+                    omittedChanges: compared.selection.omittedChangeCount,
+                    unattributedChanges: compared.selection.unattributedChangeIds.length,
+                    selectedBeforeNodes: compared.selection.beforeNodeIds.length,
+                    selectedAfterNodes: compared.selection.afterNodeIds.length,
+                }),
             addedNodes: comparison.addedNodeIds.length,
             removedNodes: comparison.removedNodeIds.length,
             changedNodes: comparison.changedNodeIds.length,
@@ -155,6 +164,13 @@ export async function compareEvents(viewer, input) {
         },
         boundary: {
             proposedSources: input.proposedSources?.length ?? 0,
+            ...(compared.selection === undefined
+                ? {}
+                : {
+                    selector: compared.selection.selector,
+                    maxChainNodes: compared.selection.maxChainNodes,
+                    selectionTruncated: compared.selection.truncated,
+                }),
             render: input.render ?? true,
             maxRenderNodes: input.maxRenderNodes ?? 120,
             refresh: compared.refresh,

package/dist/hoi4_agent_tools/event/service.js

@@ -13,6 +13,7 @@ import { buildEventGraph, buildEventGraphAsync } from './graph.js';
 import { EVENT_FRAGMENT_CACHE_MAX_ENTRIES, EVENT_FRAGMENT_CACHE_MAX_SOURCE_BYTES, EVENT_PROPOSED_SOURCE_MAX_BYTES, EVENT_PROPOSED_SOURCE_MAX_FILES, } from './limits.js';
 import { analyzeEventImpact, discoverEventRoots, explainEventPath, inspectEventStateFlow, lintEventGraph, traceSelectedEvents, } from './queries.js';
 import { compareEventGraphs, eventGraphHash } from './compare.js';
+import { selectEventComparison } from './comparison-selection.js';
 import { eventFlowEdges } from './algorithms.js';
 import { validateEventGraphArtifact } from './artifact-validation.js';
 import { renderEventGraph, } from './render.js';
@@ -1331,16 +1332,29 @@ export class EventChainViewer {
             after = current;
         }
         const comparison = compareEventGraphs(before, after, input.signal);
+        const selection = input.selector === undefined
+            ? undefined
+            : selectEventComparison(before, after, comparison, input.selector, input.maxChainNodes ?? 1_000, input.signal);
+        if (selection?.beforeNodeIds.length === 0 && selection.afterNodeIds.length === 0)
+            throw new ServiceError('EVENT_COMPARISON_SELECTOR_NOT_FOUND', 'The selector matched no event-chain nodes in either revision');
         graphHashCache.set(before, comparison.beforeGraphHash);
         graphHashCache.set(after, comparison.afterGraphHash);
         let render;
         if (input.render !== false) {
             const projection = comparisonRenderProjection(before, after, comparison, input.signal);
+            const selectedChainIds = selection === undefined
+                ? undefined
+                : new Set([...selection.beforeNodeIds, ...selection.afterNodeIds]);
+            const changedNodeIds = selectedChainIds === undefined
+                ? projection.selectedNodeIds
+                : projection.selectedNodeIds.filter((id) => selectedChainIds.has(id));
             const selector = {
                 kind: 'manifest',
                 manifest: {
                     id: 'comparison',
-                    nodeIds: projection.selectedNodeIds,
+                    nodeIds: changedNodeIds.length > 0
+                        ? changedNodeIds
+                        : (selection?.afterNodeIds.slice(0, 1) ?? selection?.beforeNodeIds.slice(0, 1) ?? []),
                 },
             };
             render = await renderEventGraph(projection.graph, {
@@ -1354,7 +1368,7 @@ export class EventChainViewer {
             });
         }
         const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
-        const prefix = safeSlug(`event-compare-${before.revision.slice(0, 8)}-${after.revision.slice(0, 8)}`);
+        const prefix = safeSlug(`event-compare-${before.revision.slice(0, 8)}-${after.revision.slice(0, 8)}${selection === undefined ? '' : `-${hashCanonical({ selector: selection.selector, maxChainNodes: selection.maxChainNodes }).slice(0, 8)}`}`);
         const resourceNames = {
             json: `${prefix}.json`,
             ...(render === undefined
@@ -1380,6 +1394,9 @@ export class EventChainViewer {
             filters: {
                 ...(input.before === undefined ? {} : { before: input.before }),
                 ...(input.after === undefined ? {} : { after: input.after }),
+                ...(input.selector === undefined
+                    ? {}
+                    : { selector: input.selector, maxChainNodes: input.maxChainNodes ?? 1_000 }),
                 proposedSources: input.proposedSources?.map(({ relativePath, source, expectedSourceHash }) => ({
                     relativePath,
                     operation: source === null ? 'delete' : 'overlay',
@@ -1397,6 +1414,7 @@ export class EventChainViewer {
             evidence: comparisonEntityEvidence(before, after, comparison, input.signal),
             resources: resourceNames,
             comparison,
+            ...(selection === undefined ? {} : { selection }),
         })}\n`;
         const provenance = eventProvenance(after, 'event-comparison', {
             beforeRevision: before.revision,
@@ -1447,6 +1465,7 @@ export class EventChainViewer {
             after,
             refresh,
             comparison,
+            ...(selection === undefined ? {} : { selection }),
             comparisonJson,
             ...(render === undefined ? {} : { render }),
             artifacts,