hoi4-agent-tools 4.0.4 → 4.1.0

package/dist/hoi4_agent_tools/map/render.js

@@ -402,10 +402,18 @@ export async function renderMap(index, options = {}) {
         throw new ServiceError('MAP_TILE_OUT_OF_BOUNDS', 'Map tile extends beyond the province raster', { tile, rasterWidth: raster.width, rasterHeight: raster.height });
     const outputDimensions = budget.reserve((tile?.width ?? raster.width) * resolved.scale, (tile?.height ?? raster.height) * resolved.scale, 'map PNG output');
     const raw = Buffer.alloc(raster.width * raster.height * 4);
+    // A base layer assigns one color to each province. Resolve that color once for this
+    // immutable render, rather than repeating state lookups and color hashes for every pixel.
+    const provinceColors = new Map();
     for (let offset = 0; offset < raster.provinceIds.length; offset += 1) {
         if (offset % Math.max(raster.width * 32, 1) === 0)
             await renderCheckpoint(options.signal);
-        const color = baseColor(index, raster.provinceIds[offset] ?? -1, resolved.layer);
+        const provinceId = raster.provinceIds[offset] ?? -1;
+        let color = provinceColors.get(provinceId);
+        if (color === undefined) {
+            color = baseColor(index, provinceId, resolved.layer);
+            provinceColors.set(provinceId, color);
+        }
         const target = offset * 4;
         raw[target] = color.r;
         raw[target + 1] = color.g;

package/dist/hoi4_agent_tools/map/service.js

@@ -4,6 +4,7 @@ import { escapeFileGlob } from '../core/file-glob.js';
 import { ArtifactStore, boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
 import { canonicalJson, compareCodeUnits, hashCanonical, sha256Bytes } from '../core/canonical.js';
 import { sortDiagnostics } from '../core/diagnostics.js';
+import { diagnosticSeverityCounts, rollupRepeatedSoftDiagnostics, } from '../core/diagnostic-rollup.js';
 import { CoreEngine } from '../core/engine.js';
 import { SymbolIndex } from '../core/index.js';
 import { RenderBudget } from '../core/render-budget.js';
@@ -13,9 +14,12 @@ import { readDependenciesFromScannedFiles, } from '../core/transactions.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT, MAP_SELECTED_OFFSET_BYTES, MAP_SELECTED_PIXEL_LIMIT, } from './limits.js';
 import { defaultMapSelectorValue, MapWorkspaceIndex, } from './model.js';
-import { planMapOperationsAsync } from './operations.js';
+import { planMapOperationsAsync, } from './operations.js';
+import { prepareReferenceWorld } from './reference-preparation.js';
+import { WORLD_OUTPUT_MANIFEST } from './world-outputs.js';
 import { renderMap, renderMapDiff, } from './render.js';
 import { validateMapAsync } from './validation.js';
+import { buildWorldPreviewArtifacts, generatedWorldOperationIds } from './world-preview.js';
 function compareNumbers(left, right) {
     return left - right;
 }
@@ -384,6 +388,7 @@ function sourceTextPatterns(roots) {
         'common/terrain/*.txt',
         'common/buildings/*.txt',
         'descriptor.mod',
+        WORLD_OUTPUT_MANIFEST,
         ...roots.map.flatMap((root) => {
             const normalized = normalizeSourceRoot(root);
             return ['map', 'csv', 'txt'].map((extension) => `${normalized}/**/*.${extension}`);
@@ -391,7 +396,11 @@ function sourceTextPatterns(roots) {
         ...roots.states.map((root) => `${normalizeSourceRoot(root)}/**/*.txt`),
         ...roots.localisation.flatMap((root) => {
             const normalized = normalizeSourceRoot(root);
-            return [`${normalized}/english/**/*.{yml,yaml}`, `${normalized}/*.{yml,yaml}`];
+            return [
+                `${normalized}/english/**/*.{yml,yaml}`,
+                `${normalized}/replace/**/*.{yml,yaml}`,
+                `${normalized}/*.{yml,yaml}`,
+            ];
         }),
     ];
 }
@@ -441,8 +450,42 @@ function provinceBitmapPatterns(defaultMaps, mapRoots) {
     }
     return [...patterns].sort((left, right) => compareCodeUnits(left, right));
 }
+function mapSourceEvidence(snapshot) {
+    if (snapshot.referenceSources === undefined)
+        return snapshot.files;
+    return [
+        ...new Map([...snapshot.files, ...(snapshot.referenceSources ?? [])].map((source) => [
+            source.displayPath,
+            source,
+        ])).values(),
+    ].sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+}
 function sourceHashes(snapshot) {
-    return Object.fromEntries(snapshot.files.map(({ displayPath, sha256 }) => [displayPath, sha256]));
+    return Object.fromEntries(mapSourceEvidence(snapshot).map(({ displayPath, sha256 }) => [displayPath, sha256]));
+}
+function mapValidationEvidence(snapshot, validation) {
+    const evidence = boundedSourceHashEvidence(sourceHashes(snapshot));
+    const counts = diagnosticSeverityCounts(validation.diagnostics);
+    const omissions = validation.diagnostics
+        .filter((diagnostic) => diagnostic.code === 'MAP_DIAGNOSTICS_TRUNCATED')
+        .map((diagnostic) => diagnostic.details ?? {});
+    return {
+        name: 'map-validation.json',
+        mimeType: 'application/json',
+        content: `${canonicalJson({ schemaVersion: 1, passed: validation.passed, checks: validation.checks, diagnosticCount: validation.diagnostics.length, counts, diagnostics: validation.diagnostics, omissionEvidence: omissions })}\n`,
+        description: 'Complete bounded map validation diagnostics, counts and omission evidence',
+        provenance: {
+            kind: 'map-validation',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'map-validation.v1',
+            sourceHashes: evidence.sourceHashes,
+            metadata: {
+                sourceRevision: snapshot.revision,
+                sourceHashInventory: evidence.inventory,
+                diagnosticCount: validation.diagnostics.length,
+            },
+        },
+    };
 }
 function mapBundleWithSourceHashes(bundle, completeSourceHashes) {
     const parsed = JSON.parse(bundle.json);
@@ -529,7 +572,7 @@ export class AgentNudger {
         this.scanner = this.engine.scanner;
         this.transactions = this.engine.transactions;
     }
-    async scan(workspaceId, principal, signal, includeExternalScriptReferences = false) {
+    async scan(workspaceId, principal, signal, includeExternalScriptReferences = false, includeWorldContext = false) {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
         const sourceRoots = {
@@ -546,11 +589,38 @@ export class AgentNudger {
                 patterns: [...MAP_REFERENCE_SCRIPT_PATTERNS],
             }, principal, signal)
             : undefined;
+        const worldContextSnapshot = includeWorldContext
+            ? await this.engine.scan(workspaceId, {
+                patterns: [
+                    'common/state_category/**/*.txt',
+                    'common/country_tags/*.txt',
+                    ...sourceRoots.map.flatMap((root) => ['terrain', 'rivers', 'trees', 'cities'].map((name) => `${root}/${name}.bmp`)),
+                ],
+            }, principal, signal)
+            : undefined;
+        const generatedOutputsSnapshot = includeWorldContext
+            ? await this.engine.scan(workspaceId, {
+                rootKinds: ['mod'],
+                patterns: [
+                    'common/countries/*.txt',
+                    'common/country_tags/*.txt',
+                    'history/countries/*.txt',
+                    'history/units/*.txt',
+                    'common/on_actions/world.txt',
+                    'common/ai_areas/world.txt',
+                    'common/ai_strategy_plans/world.txt',
+                    'gfx/flags/**/*.tga',
+                    ...sourceRoots.map.flatMap((root) => [`${root}/**/*.bmp`, `${root}/terrain/*.dds`]),
+                ],
+            }, principal, signal)
+            : undefined;
         signal?.throwIfAborted();
         const files = [
             ...contentSnapshot.files,
             ...locatorSnapshot.files,
             ...(externalScriptSnapshot?.files ?? []),
+            ...(worldContextSnapshot?.files ?? []).filter((file) => !contentSnapshot.files.some((existing) => existing.displayPath === file.displayPath)),
+            ...(generatedOutputsSnapshot?.files ?? []).filter((file) => ![...contentSnapshot.files, ...(worldContextSnapshot?.files ?? [])].some((existing) => existing.displayPath === file.displayPath)),
         ].sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
         const revision = hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 })));
         return {
@@ -590,11 +660,43 @@ export class AgentNudger {
         signal?.throwIfAborted();
         const snapshot = await this.scan(workspaceId, principal, signal, operations.some((operation) => operation.kind === 'renumber_map_entity' ||
             operation.kind === 'remap_map_references' ||
-            'remapReferences' in operation));
-        const plan = await planMapOperationsAsync(snapshot.index, operations, signal);
-        const baselineValidation = await validateMapAsync(snapshot.index, signal === undefined ? {} : { signal });
-        // A new world has nothing to compare its bitmap format and pixels with.
+            'remapReferences' in operation), operations.some((operation) => operation.kind === 'create_world'));
+        const referenceWorlds = new Map();
+        const referenceImages = [];
+        for (const operation of operations) {
+            if (operation.kind !== 'create_world' || operation.reference === undefined)
+                continue;
+            const loaded = await prepareReferenceWorld(this.resolver, workspaceId, operation, principal, signal);
+            referenceWorlds.set(operation.id, loaded.prepared);
+            referenceImages.push({
+                operationId: operation.id,
+                bytes: loaded.images[0].bytes,
+                source: loaded.images[0].source,
+            });
+            for (const image of loaded.images) {
+                snapshot.referenceSources ??= [];
+                const previous = snapshot.referenceSources.findIndex((file) => file.displayPath === image.source.displayPath);
+                if (previous < 0)
+                    snapshot.referenceSources.push(image.source);
+                else
+                    snapshot.referenceSources[previous] = image.source;
+            }
+        }
+        snapshot.files.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+        snapshot.revision = hashCanonical(mapSourceEvidence(snapshot).map(({ displayPath, loadOrder, sha256 }) => ({
+            displayPath,
+            loadOrder,
+            sha256,
+        })));
+        const plan = await planMapOperationsAsync(snapshot.index, operations, signal, {
+            referenceWorlds,
+        });
         const newWorld = operations.some(({ kind }) => kind === 'create_world');
+        const freshWorld = newWorld && snapshot.index.provinceBitmapFile?.rootKind !== 'mod';
+        const baselineValidation = freshWorld
+            ? { passed: true, diagnostics: [], checks: [] }
+            : await validateMapAsync(snapshot.index, signal === undefined ? {} : { signal });
+        // A new world has nothing to compare its bitmap format and pixels with.
         const rawValidation = await validateMapAsync(plan.finalIndex, {
             ...(newWorld ? {} : { baseline: snapshot.index }),
             ...(signal === undefined ? {} : { signal }),
@@ -615,6 +717,7 @@ export class AgentNudger {
             snapshot,
             plan,
             validation: validationWithPlan(attributedValidation, plan),
+            referenceImages,
         };
     }
     async plan(input) {
@@ -627,15 +730,24 @@ export class AgentNudger {
         if (snapshot.workspaceId !== input.workspaceId) {
             throw new ServiceError('MAP_PREPARED_WORKSPACE_MISMATCH', 'Prepared map operations belong to another workspace');
         }
+        const reportWrite = mapValidationEvidence(snapshot, validation);
+        const existingReport = input.artifacts?.find(({ name }) => name === reportWrite.name ||
+            (name.startsWith(`${reportWrite.name}.`) && name.endsWith('.chunks.json')));
+        const report = existingReport ??
+            publicArtifactLink(await this.artifacts.putChunked(this.resolver.get(input.workspaceId, input.principal), reportWrite.name, reportWrite.mimeType, reportWrite.content, reportWrite.provenance, reportWrite.description, input.signal));
+        const journalDiagnostics = rollupRepeatedSoftDiagnostics(validation.diagnostics, report);
+        const artifacts = [
+            ...(input.artifacts ?? []),
+            ...(existingReport === undefined ? [report] : []),
+        ];
         const transaction = await this.transactions.plan({
             workspaceId: input.workspaceId,
             ...(input.principal === undefined ? {} : { principal: input.principal }),
             operationKind: 'agent-nudger-map-changes',
             operations: plan.operations,
             changes: plan.changes,
-            readDependencies: readDependenciesFromScannedFiles(snapshot.files),
-            ...(input.artifacts === undefined ? {} : { artifacts: input.artifacts }),
-            diagnostics: plan.diagnostics,
+            readDependencies: readDependenciesFromScannedFiles(mapSourceEvidence(snapshot)),
+            artifacts,
             validate: (proposed, signal) => {
                 signal?.throwIfAborted();
                 const expected = new Map(plan.changes.map((change) => [change.relativePath, change.content]));
@@ -655,9 +767,9 @@ export class AgentNudger {
                     }) &&
                     [...proposed.keys()].every((relativePath) => expected.has(relativePath));
                 const diagnostics = exactProposedBytes
-                    ? validation.diagnostics
+                    ? journalDiagnostics
                     : [
-                        ...validation.diagnostics,
+                        ...journalDiagnostics,
                         {
                             code: 'MAP_TRANSACTION_BYTES_MISMATCH',
                             severity: 'blocker',
@@ -737,7 +849,7 @@ export class AgentNudger {
             bundle,
             artifacts,
             revision: snapshot.revision,
-            filesScanned: snapshot.files.map(({ displayPath }) => displayPath),
+            filesScanned: mapSourceEvidence(snapshot).map(({ displayPath }) => displayPath),
         };
     }
     async renderDiffAndStore(workspaceId, operations, options = {}) {
@@ -764,9 +876,30 @@ export class AgentNudger {
         }, prepared);
         return { ...diff, ...planned };
     }
+    /** Build validated offline evidence without planning or applying a write transaction. */
+    async previewRewriteWithDiff(input) {
+        const prepared = await this.prepareOperations(input.workspaceId, input.operations, input.principal, input.signal);
+        const diff = await this.renderPreparedDiffAndStore(prepared, input.operations, {
+            ...(input.diffScale === undefined ? {} : { scale: input.diffScale }),
+            ...(input.principal === undefined ? {} : { principal: input.principal }),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        return {
+            ...diff,
+            validation: prepared.validation,
+            diagnostics: rollupRepeatedSoftDiagnostics(prepared.validation.diagnostics, publicArtifactLink(diff.artifacts.find((artifact) => artifact.name === 'map-validation.json' ||
+                (artifact.name.startsWith('map-validation.json.') &&
+                    artifact.name.endsWith('.chunks.json'))))),
+        };
+    }
     async renderPreparedDiffAndStore(prepared, operations, options) {
         const budget = new RenderBudget();
         const { snapshot, plan, validation } = prepared;
+        const failedWorld = operations.some(({ kind }) => kind === 'create_world') &&
+            generatedWorldOperationIds(plan).size === 0 &&
+            plan.changes.length === 0;
+        // A rolled-back generation has no proposed world. Never present inherited game geography
+        // or all its province IDs as the result of a failed operation.
         const review = {
             operationIds: plan.operations.map(({ id }) => id),
             affectedFiles: plan.changes.map(({ relativePath, operationIds, mediaType, content }) => ({
@@ -784,6 +917,63 @@ export class AgentNudger {
             allocations: plan.allocations,
             validation,
         };
+        if (failedWorld) {
+            const report = mapValidationEvidence(snapshot, validation);
+            const json = canonicalJson({ generated: false, blockers: plan.blockers });
+            const emptyHash = sha256Bytes('');
+            // No raster exists after a failed first generation. This empty internal bundle is never
+            // published as an image; it carries only zero changed IDs to the normal result adapter.
+            const bundle = {
+                width: 0,
+                height: 0,
+                png: Buffer.alloc(0),
+                json,
+                html: '',
+                hashes: { png: emptyHash, json: sha256Bytes(json), html: emptyHash },
+                changedProvinceIds: [],
+                review,
+                semantic: {
+                    definitions: [],
+                    stateMembership: [],
+                    regionMembership: [],
+                    states: [],
+                    ports: [],
+                    buildingPositions: [],
+                    unitPositions: [],
+                    weatherPositions: [],
+                    entityLocators: [],
+                    supplyNodes: [],
+                    railways: [],
+                    adjacencies: [],
+                    normalAdjacencies: [],
+                    supplyNodesChanged: false,
+                    railwaysChanged: false,
+                    adjacenciesChanged: false,
+                    normalAdjacenciesChanged: false,
+                },
+            };
+            const artifacts = await this.artifacts.withAtomicChunkedWrites(this.resolver.get(snapshot.workspaceId, options.principal), [
+                report,
+                {
+                    name: 'map-generation-failure.json',
+                    mimeType: 'application/json',
+                    content: json,
+                    provenance: {
+                        ...report.provenance,
+                        kind: 'map-generation-failure',
+                        schemaVersion: 'map-generation-failure.v1',
+                    },
+                },
+            ], (stored) => Promise.resolve([...stored]), options.signal);
+            return {
+                bundle,
+                proposedBundle: bundle,
+                plan,
+                artifacts,
+                revision: snapshot.revision,
+                filesScanned: mapSourceEvidence(snapshot).map(({ displayPath }) => displayPath),
+            };
+        }
         const comparisonOverlays = [
             'adjacencies',
             'building-positions',
@@ -798,13 +988,16 @@ export class AgentNudger {
             'victory-points',
             'weather-positions',
         ];
-        const hasBeforeMap = snapshot.index.raster !== undefined ||
-            snapshot.index.diagnostics.some(({ code }) => code.startsWith('RENDER_'));
+        const freshWorld = operations.some(({ kind }) => kind === 'create_world') &&
+            snapshot.index.provinceBitmapFile?.rootKind !== 'mod';
+        const hasBeforeMap = !freshWorld &&
+            (snapshot.index.raster !== undefined ||
+                snapshot.index.diagnostics.some(({ code }) => code.startsWith('RENDER_')));
         const sameSize = snapshot.index.provinceBitmap !== undefined &&
             snapshot.index.provinceBitmap.width === plan.finalIndex.provinceBitmap?.width &&
             snapshot.index.provinceBitmap.height === plan.finalIndex.provinceBitmap.height;
         const [rawBundle, rawBeforeBundle, rawProposedBundle] = await Promise.all([
-            sameSize
+            sameSize && !freshWorld
                 ? renderMapDiff(snapshot.index, plan.finalIndex, {
                     ...(options.scale === undefined ? {} : { scale: options.scale }),
                     ...(options.signal === undefined ? {} : { signal: options.signal }),
@@ -874,6 +1067,7 @@ export class AgentNudger {
             },
         });
         const writes = [
+            mapValidationEvidence(snapshot, validation),
             {
                 name: 'map-diff.png',
                 mimeType: 'image/png',
@@ -928,6 +1122,16 @@ export class AgentNudger {
                 content: beforeBundle.html,
                 provenance: comparisonProvenance('before'),
             });
+        const generatedWorlds = generatedWorldOperationIds(plan);
+        if (generatedWorlds.size > 0)
+            writes.push(...(await buildWorldPreviewArtifacts({
+                index: plan.finalIndex,
+                references: prepared.referenceImages.filter(({ operationId }) => generatedWorlds.has(operationId)),
+                diagnostics: validation.diagnostics,
+                provenance,
+                budget,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            })));
         const artifacts = await this.artifacts.withAtomicChunkedWrites(workspace, writes, (stored) => Promise.resolve([...stored]), options.signal);
         return {
             bundle,
@@ -936,7 +1140,7 @@ export class AgentNudger {
             plan,
             artifacts,
             revision: snapshot.revision,
-            filesScanned: snapshot.files.map(({ displayPath }) => displayPath),
+            filesScanned: mapSourceEvidence(snapshot).map(({ displayPath }) => displayPath),
         };
     }
 }

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

@@ -1,5 +1,6 @@
 import { boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
 import { canonicalJson, hashCanonical } from '../core/canonical.js';
+import { diagnosticSeverityCounts } from '../core/diagnostic-rollup.js';
 import { autonomousResultArtifacts, } from '../core/transaction-execution.js';
 import { emptyServiceResult, ServiceError } from '../core/result.js';
 import { setInlineFilesScanned } from '../core/operation-result.js';
@@ -8,6 +9,7 @@ import { allocateMapIdentifiersAsync, } from './operations.js';
 import { buildMapCatalog, lookupMapCoordinate, searchMapCatalog } from './catalog.js';
 import { renderMap } from './render.js';
 import { exportProvinceGeometryRowRuns } from './service.js';
+import { generatedWorldOperationIds } from './world-preview.js';
 const jsonObject = z.record(z.string(), z.json());
 const mapRewriteRecipeSchema = z
     .object({
@@ -44,7 +46,7 @@ function compactRecordDiffs(entries) {
         after: compactNullableText(after),
     }));
 }
-function compactMapSemanticDiff(semantic) {
+export function compactMapSemanticDiff(semantic) {
     const counts = {
         definitions: semantic.definitions.length,
         stateMembership: semantic.stateMembership.length,
@@ -60,7 +62,7 @@ function compactMapSemanticDiff(semantic) {
         adjacencies: semantic.adjacencies.length,
         normalAdjacencies: semantic.normalAdjacencies.length,
     };
-    return {
+    const result = {
         semantic: {
             definitions: semantic.definitions
                 .slice(0, mapInlineDiffLimit)
@@ -113,6 +115,15 @@ function compactMapSemanticDiff(semantic) {
                 (before?.length ?? 0) > mapInlineTextLimit ||
                 (after?.length ?? 0) > mapInlineTextLimit),
     };
+    // Bound the aggregate, not just each collection: a complete world replaces every category.
+    // Full diffs remain in map-diff.json; leave enough wire space for preview image links.
+    while (Buffer.byteLength(canonicalJson(result.semantic), 'utf8') > 8_192) {
+        for (const value of Object.values(result.semantic))
+            if (Array.isArray(value))
+                value.splice(Math.floor(value.length / 2));
+        result.truncated = true;
+    }
+    return result;
 }
 function validationSummary(validation) {
     return { passed: validation.passed, checks: validation.checks };
@@ -297,6 +308,64 @@ export function completeMapRewrite(workspaceId, execution, recipe) {
     ].slice(0, 100);
     return result;
 }
+/** Generate and validate the same proposed map without creating a write transaction. */
+export async function previewMapRewrite(nudger, input, context) {
+    await context.progress(0, 5, 'Generating and validating an offline map preview');
+    const planned = await nudger.previewRewriteWithDiff({
+        workspaceId: context.workspaceId,
+        operations: input.operations,
+        ...(input.diffScale === undefined ? {} : { diffScale: input.diffScale }),
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+    });
+    const compactSemantic = compactMapSemanticDiff(planned.bundle.semantic);
+    const index = planned.plan.finalIndex;
+    const result = emptyServiceResult(context.workspaceId, {
+        execution: 'preview',
+        allocations: planned.plan.allocations.slice(0, 100).map(compactAllocationEvidence),
+        operationBlockers: planned.plan.blockers
+            .slice(0, 100)
+            .map(({ code, message, operationId }) => ({ code, message, operationId })),
+        expectedChangedBounds: planned.plan.expectedChangedBounds ?? null,
+        changedProvinceIds: planned.bundle.changedProvinceIds.slice(0, 256),
+        changedProvinceCount: planned.bundle.changedProvinceIds.length,
+        semanticDiff: compactSemantic.semantic,
+        semanticDiffCounts: compactSemantic.counts,
+        semanticDiffTruncated: compactSemantic.truncated,
+        fileCount: planned.plan.changes.length,
+        artifactCount: planned.artifacts.length,
+        ...(input.operations.some(({ kind }) => kind === 'create_world') &&
+            generatedWorldOperationIds(planned.plan).size === 0
+            ? {}
+            : {
+                preview: {
+                    offlineRepresentation: true,
+                    width: index.raster?.width ?? 0,
+                    height: index.raster?.height ?? 0,
+                    provinces: index.definitions.filter(({ id }) => id !== 0).length,
+                    states: index.states.length,
+                    regions: index.regions.length,
+                    countries: new Set(index.states.flatMap(({ owner }) => (owner === undefined ? [] : [owner]))).size,
+                    warningCount: diagnosticSeverityCounts(planned.diagnostics).warning,
+                },
+            }),
+    });
+    result.status = planned.validation.passed ? 'ok' : 'blocked';
+    result.code = planned.validation.passed ? 'MAP_PREVIEW_READY' : 'MAP_PREVIEW_BLOCKED';
+    setInlineFilesScanned(result, planned.filesScanned);
+    result.proposedFiles = planned.plan.changes.slice(0, 100).map(({ relativePath }) => relativePath);
+    result.diagnostics = planned.diagnostics.slice(0, 100);
+    result.artifacts = planned.artifacts.map(publicArtifactLink);
+    result.validation = validationSummary(planned.validation);
+    result.blockers = [
+        ...planned.plan.blockers.map(({ code, message }) => ({ code, message })),
+        ...planned.diagnostics
+            .filter(({ severity }) => severity === 'error' || severity === 'blocker')
+            .map(({ code, message }) => ({ code, message })),
+    ].slice(0, 100);
+    await context.progress(5, 5, 'Offline map preview complete; workspace files were not changed');
+    return result;
+}
 export async function inspectMap(engine, nudger, input, context) {
     await context.progress(0, 3, 'Inspecting and validating the map');
     if (input.lookupOnly) {

package/dist/hoi4_agent_tools/map/world-context.js

@@ -0,0 +1,148 @@
+import { compareCodeUnits } from '../core/canonical.js';
+import { hasBlockingDiagnostics } from '../core/diagnostics.js';
+import { ServiceError } from '../core/result.js';
+import { assignments, childBlocks, firstScalar, parseClausewitz } from '../core/source/index.js';
+import { BmpImage } from './bmp.js';
+function normalized(value) {
+    return value.replaceAll('\\', '/').replace(/^\.\//u, '').toLowerCase();
+}
+function invalid(file, message) {
+    throw new ServiceError('MAP_WORLD_CONTEXT_INVALID', message, { file: file.displayPath });
+}
+function documentFor(file) {
+    const document = parseClausewitz(file.bytes, file.displayPath);
+    if (hasBlockingDiagnostics(document.diagnostics))
+        invalid(file, 'Installed world conventions contain malformed Clausewitz syntax.');
+    return document;
+}
+/**
+ * Build conventions exclusively from authorized, already-scanned active sources. Missing
+ * conventions retain the generator's defaults; present but invalid conventions are refused.
+ * Source bitmap bytes and script files are never modified or copied into generated mod files.
+ */
+export function buildWorldContext(base) {
+    const context = {
+        palettes: {},
+        mapRoot: base.sourceRoots.map[0] ?? 'map',
+        statesRoot: base.sourceRoots.states[0] ?? 'history/states',
+        localisationRoot: base.sourceRoots.localisation[0] ?? 'localisation',
+    };
+    const continentKeys = new Set();
+    for (const file of base.sourceFiles.filter((file) => base.sourceRoots.map.some((root) => normalized(file.relativePath) === normalized(`${root}/continent.txt`)))) {
+        for (const block of childBlocks(documentFor(file).root, 'continents')) {
+            for (const entry of block.entries) {
+                if (entry.type !== 'scalar' || !/^[a-zA-Z_][a-zA-Z0-9_]*$/u.test(entry.value))
+                    invalid(file, 'Continent identifiers must be simple scalar keys.');
+                continentKeys.add(entry.value);
+            }
+        }
+    }
+    if (continentKeys.size)
+        context.continentKeys = [...continentKeys].sort(compareCodeUnits);
+    const inheritedCountryTags = new Set();
+    for (const file of base.activeFiles.all.filter((file) => /^common\/country_tags\/[^/]+\.txt$/u.test(normalized(file.relativePath))))
+        for (const entry of assignments(documentFor(file).root))
+            if (/^[A-Z][A-Z0-9]{2}$/u.test(entry.key.value) && entry.value.type === 'scalar')
+                inheritedCountryTags.add(entry.key.value);
+    if (inheritedCountryTags.size)
+        context.inheritedCountryTags = [...inheritedCountryTags].sort(compareCodeUnits);
+    for (const name of ['terrain', 'rivers', 'trees', 'cities']) {
+        const file = base.sourceRoots.map
+            .map((root) => base.activeFiles.byRelativePath.get(normalized(`${root}/${name}.bmp`)))
+            .find((entry) => entry !== undefined);
+        if (file === undefined)
+            continue;
+        let bitmap;
+        try {
+            bitmap = BmpImage.decode(file.bytes);
+        }
+        catch {
+            invalid(file, `The installed ${name} bitmap is malformed or unsupported.`);
+        }
+        const minimumEntries = { terrain: 22, rivers: 256, trees: 30, cities: 16 }[name];
+        if (bitmap.bitsPerPixel !== 8 || bitmap.palette.length < minimumEntries)
+            invalid(file, `The installed ${name} bitmap requires an 8-bit palette with at least ${minimumEntries} entries.`);
+        context.palettes[name] = bitmap.palette.map((color) => ({ ...color }));
+    }
+    const terrainFiles = base.activeFiles.all
+        .filter((file) => /^common\/terrain\/[^/]+\.txt$/u.test(normalized(file.relativePath)))
+        .sort((a, b) => compareCodeUnits(normalized(a.relativePath), normalized(b.relativePath)));
+    const terrainIndex = new Map();
+    for (const file of terrainFiles) {
+        const candidates = new Map();
+        const terrain = assignments(documentFor(file).root, 'terrain');
+        for (const section of terrain)
+            if (section.value.type !== 'block')
+                invalid(file, 'Graphical terrain sections must be blocks.');
+        for (const { value: block } of terrain) {
+            if (block.type !== 'block')
+                continue;
+            if (block.entries.some((entry) => entry.type !== 'assignment'))
+                invalid(file, 'Graphical terrain sections require named entries.');
+            for (const entry of assignments(block)) {
+                if (entry.value.type !== 'block')
+                    invalid(file, 'Graphical terrain entries must be blocks.');
+                const type = firstScalar(entry.value, 'type')?.value;
+                const colors = childBlocks(entry.value, 'color');
+                if (type === undefined ||
+                    type.length === 0 ||
+                    assignments(entry.value, 'type').length !== 1 ||
+                    assignments(entry.value, 'color').length !== 1 ||
+                    colors.length !== 1 ||
+                    colors[0].entries.length === 0)
+                    invalid(file, 'Graphical terrain requires a type and a nonempty color-index block.');
+                let index = 256;
+                for (const color of colors[0].entries) {
+                    if (color.type !== 'scalar' || !/^\d+$/u.test(color.value))
+                        invalid(file, 'Graphical terrain colors must be integer palette indices.');
+                    const value = Number(color.value);
+                    if (!Number.isSafeInteger(value) || value > 255)
+                        invalid(file, 'Graphical terrain palette indices must be between 0 and 255.');
+                    if (context.palettes.terrain !== undefined && value >= context.palettes.terrain.length)
+                        invalid(file, 'Graphical terrain refers to a missing terrain palette entry.');
+                    index = Math.min(index, value);
+                }
+                // Prefer ordinary category variants over cross-category names or permanent snow.
+                // Within an equal rank, the lowest declared index is the stable representative.
+                const name = entry.key.value;
+                let rank = name === type ? 0 : name.startsWith(`${type}_`) || /^terrain_\d+$/u.test(name) ? 1 : 2;
+                if (firstScalar(entry.value, 'perm_snow')?.value === 'yes')
+                    rank += 4;
+                const previous = candidates.get(type);
+                if (previous === undefined ||
+                    rank < previous.rank ||
+                    (rank === previous.rank && index < previous.index))
+                    candidates.set(type, { index, rank });
+            }
+        }
+        // Later active filenames replace an earlier file's representative for that category.
+        for (const [type, candidate] of candidates)
+            terrainIndex.set(type, candidate.index);
+    }
+    if (terrainIndex.size > 0)
+        context.terrainIndex = new Map([...terrainIndex].sort(([a], [b]) => compareCodeUnits(a, b)));
+    const categoryFiles = base.activeFiles.all
+        .filter((file) => /^common\/state_category\/[^/]+\.txt$/u.test(normalized(file.relativePath)))
+        .sort((a, b) => compareCodeUnits(normalized(a.relativePath), normalized(b.relativePath)));
+    if (categoryFiles.length > 0) {
+        const categories = new Set();
+        for (const file of categoryFiles) {
+            const blocks = childBlocks(documentFor(file).root, 'state_categories');
+            if (blocks.length === 0)
+                invalid(file, 'State category conventions require a state_categories block.');
+            for (const block of blocks) {
+                if (block.entries.some((entry) => entry.type !== 'assignment'))
+                    invalid(file, 'State category conventions require named entries.');
+                for (const entry of assignments(block)) {
+                    if (entry.value.type !== 'block')
+                        invalid(file, 'State category definitions must be blocks.');
+                    categories.add(entry.key.value);
+                }
+            }
+        }
+        if (categories.size === 0)
+            invalid(categoryFiles[0], 'Installed state category conventions define no categories.');
+        context.stateCategories = new Set([...categories].sort(compareCodeUnits));
+    }
+    return context;
+}