hoi4-agent-tools 2.5.3 → 2.6.0

package/dist/hoi4_agent_tools/map/render.js

@@ -2,6 +2,7 @@ import sharp from 'sharp';
 import { compareCodeUnits, canonicalJson, sha256Bytes } from '../core/canonical.js';
 import { assertRenderDimensions, RenderBudget, RENDER_MAX_PIXELS } from '../core/render-budget.js';
 import { ServiceError } from '../core/result.js';
+import { buildMapCatalog } from './catalog.js';
 import { validateMapAsync } from './validation.js';
 function stableColor(key) {
     const hash = sha256Bytes(key);
@@ -277,163 +278,55 @@ async function applyOverlays(index, bytes, overlays, signal) {
     }
 }
 async function renderMetadata(index, options, signal) {
-    const victoryPoints = index.states
-        .flatMap((state) => state.victoryPoints.map(({ provinceId, value }) => ({
-        stateId: state.id,
-        provinceId,
-        value,
-        sourcePath: state.file.displayPath,
-    })))
-        .sort((left, right) => left.stateId - right.stateId ||
-        left.provinceId - right.provinceId ||
-        left.value - right.value);
-    const normalAdjacencies = [...(index.raster?.adjacency ?? [])]
-        .flatMap(([from, neighbors]) => [...neighbors].flatMap((to) => (from < to ? [{ from, to }] : [])))
-        .sort((left, right) => left.from - right.from || left.to - right.to);
+    const catalog = buildMapCatalog(index);
     return {
-        offline: true,
-        renderer: 'hoi4-agent-tools-agent-nudger',
+        ...catalog,
+        renderer: 'hoi4-agent-tools-map-workbench',
         layer: options.layer,
         overlays: options.overlays,
         scale: options.scale,
         width: index.raster?.width ?? 0,
         height: index.raster?.height ?? 0,
-        definitions: index.definitions.map(({ id, color, type, coastal, terrain, continent }) => ({
-            id,
-            color,
-            type,
-            coastal,
-            terrain,
-            continent,
-        })),
-        states: [...index.states]
-            .sort((left, right) => left.id - right.id)
-            .map(({ id, name, capital, provinces, resources, stateBuildings, provinceBuildings, owner, controller, cores, claims, }) => ({
-            id,
-            name,
-            capital: capital ?? null,
-            manpower: index.statesById.get(id)?.manpower ?? 0,
-            category: index.statesById.get(id)?.category ?? '',
-            provinces: [...provinces].sort((a, b) => a - b),
-            resources: Object.fromEntries([...resources].sort(([left], [right]) => compareCodeUnits(left, right))),
-            stateBuildings: Object.fromEntries([...stateBuildings].sort(([left], [right]) => compareCodeUnits(left, right))),
-            provinceBuildings: Object.fromEntries([...provinceBuildings]
-                .sort(([left], [right]) => left - right)
-                .map(([provinceId, buildings]) => [
-                String(provinceId),
-                Object.fromEntries([...buildings].sort(([left], [right]) => compareCodeUnits(left, right))),
-            ])),
-            owner: owner ?? null,
-            controller: controller ?? null,
-            cores: [...cores].sort(),
-            claims: [...claims].sort(),
-        })),
-        regions: [...index.regions]
-            .sort((left, right) => left.id - right.id)
-            .map(({ id, name, provinces }) => ({
-            id,
-            name,
-            provinces: [...provinces].sort((a, b) => a - b),
-        })),
-        victoryPoints,
-        ports: [...index.ports]
-            .sort((left, right) => left.stateId - right.stateId || left.provinceId - right.provinceId)
-            .map(({ stateId, provinceId, level, coastal, adjacentSeaProvinceIds, positions }) => ({
-            stateId,
-            provinceId,
-            level,
-            coastal,
-            adjacentSeaProvinceIds: [...adjacentSeaProvinceIds].sort((left, right) => left - right),
-            positions: positions.map(({ building, x, y, z, rotation, adjacentSeaProvince, document, line }) => ({
-                building,
-                x,
-                y,
-                z,
-                rotation,
-                adjacentSeaProvince,
-                sourcePath: document.file.displayPath,
-                line,
-            })),
-        })),
-        supplyNodes: index.supplyNodes.map(({ level, provinceId, document, line }) => ({
-            level,
-            provinceId,
-            sourcePath: document.file.displayPath,
-            line,
-        })),
-        railways: index.railways.map(({ level, declaredCount, provinces, document, line }, ordinal) => ({
-            ordinal,
-            level,
-            declaredCount,
-            provinces: [...provinces],
-            sourcePath: document.file.displayPath,
-            line,
-        })),
-        adjacencies: index.adjacencies.map(({ from, to, type, through, startX, startY, stopX, stopY, rule, comment, document, line }, ordinal) => ({
-            ordinal,
-            from,
-            to,
-            type,
-            through,
-            startX,
-            startY,
-            stopX,
-            stopY,
-            rule,
-            comment,
-            sourcePath: document.file.displayPath,
-            line,
-        })),
-        normalAdjacencies,
-        buildingPositions: index.buildingPositions.map(({ stateId, building, x, y, z, rotation, adjacentSeaProvince, document, line }) => ({
-            stateId,
-            building,
-            x,
-            y,
-            z,
-            rotation,
-            adjacentSeaProvince,
-            sourcePath: document.file.displayPath,
-            line,
-        })),
-        unitPositions: index.unitPositions.map(({ provinceId, type, x, y, z, rotation, offset, document, line }) => ({
-            provinceId,
-            type,
-            x,
-            y,
-            z,
-            rotation,
-            offset,
-            sourcePath: document.file.displayPath,
-            line,
-        })),
-        weatherPositions: index.weatherPositions.map(({ strategicRegionId, x, y, z, size, document, line }) => ({
-            strategicRegionId,
-            x,
-            y,
-            z,
-            size,
-            sourcePath: document.file.displayPath,
-            line,
-        })),
-        entityLocators: [...index.entityLocators]
-            .sort((left, right) => compareCodeUnits(left.entity, right.entity) || compareCodeUnits(left.name, right.name))
-            .map(({ entity, name, position, file }) => ({
-            entity,
-            name,
-            position: [...position],
-            sourcePath: file.displayPath,
-        })),
+        definitions: catalog.provinces.map(({ id, definition }) => ({ id, ...definition })),
+        regions: catalog.strategicRegions,
+        adjacencies: catalog.specialAdjacencies,
         validation: await validateMapAsync(index, signal === undefined ? {} : { signal }),
     };
 }
-function htmlDocument(title, png, json) {
+function htmlDocument(title, png, provinceHitMap, json, renderScale) {
+    const escapedTitle = title
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+    const scriptJson = json.replaceAll('<', '\\u003c');
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapedTitle}</title><style>html{background:#10151b;color:#edf2f7;font:14px system-ui}body{margin:0;height:100vh;display:grid;grid-template-columns:minmax(0,1fr) 360px;overflow:hidden}.main{min-width:0;padding:14px;display:flex;flex-direction:column}.toolbar{display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin-bottom:10px}button,input,select{background:#202b38;color:#edf2f7;border:1px solid #526173;border-radius:4px;padding:6px 9px}input{min-width:260px;flex:1}.viewport{flex:1;min-height:0;overflow:hidden;border:1px solid #48515c;background:#080b0f;position:relative;touch-action:none}.viewport img{image-rendering:pixelated;transform-origin:0 0;position:absolute;max-width:none;cursor:grab;user-select:none}.viewport img.dragging{cursor:grabbing}.cursor{position:absolute;left:8px;bottom:8px;background:#10151bd9;padding:4px 7px;border-radius:3px;pointer-events:none}.side{border-left:1px solid #48515c;padding:14px;overflow:auto;background:#151d26}.results{display:grid;gap:4px;margin:8px 0 14px}.result{text-align:left;width:100%}.kind{color:#8fb7d9}.muted{color:#9ca9b5}pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px}h1{font-size:18px;margin:0 12px 0 0}h2{font-size:15px}</style></head><body><main class="main"><div class="toolbar"><h1>${escapedTitle}</h1><button id="out" type="button">-</button><button id="fit" type="button">Fit</button><button id="in" type="button">+</button><output id="zoom">100%</output><select id="kind"><option value="all">All IDs</option><option value="province">Provinces</option><option value="state">States</option><option value="strategic-region">Strategic regions</option></select><input id="search" type="search" placeholder="Find ID, localisation key, or name" autocomplete="off"></div><div class="viewport" id="viewport"><img id="map" draggable="false" alt="${escapedTitle}" src="data:image/png;base64,${png.toString('base64')}"><div class="cursor" id="cursor">Move over the map to inspect coordinates; click for IDs.</div></div></main><aside class="side"><h2>Search results</h2><div class="results" id="results"><span class="muted">Search by ID or name.</span></div><h2>Selection</h2><pre id="selection">Click a province or choose a search result.</pre><p class="muted">The complete source-linked catalog is embedded for navigation and is also available as the linked JSON resource.</p></aside><img id="hit" hidden src="data:image/png;base64,${provinceHitMap.toString('base64')}"><canvas id="hitCanvas" hidden></canvas><script>(()=>{const data=${scriptJson};const renderScale=${renderScale};const image=document.getElementById('map'),hit=document.getElementById('hit'),canvas=document.getElementById('hitCanvas'),viewport=document.getElementById('viewport'),zoomLabel=document.getElementById('zoom'),cursor=document.getElementById('cursor'),search=document.getElementById('search'),kind=document.getElementById('kind'),results=document.getElementById('results'),selection=document.getElementById('selection');const provinces=new Map(data.provinces.map(value=>[value.id,value])),states=new Map(data.states.map(value=>[value.id,value])),regions=new Map(data.strategicRegions.map(value=>[value.id,value]));let scale=1,x=0,y=0,drag=false,moved=false,lastX=0,lastY=0,hitContext=null;const draw=()=>{image.style.transform='translate('+x+'px,'+y+'px) scale('+scale+')';zoomLabel.value=Math.round(scale*100)+'%'};const fit=()=>{scale=Math.min(viewport.clientWidth/image.naturalWidth,viewport.clientHeight/image.naturalHeight);x=(viewport.clientWidth-image.naturalWidth*scale)/2;y=(viewport.clientHeight-image.naturalHeight*scale)/2;draw()};const zoom=(factor,cx=viewport.clientWidth/2,cy=viewport.clientHeight/2)=>{const next=Math.min(32,Math.max(.03,scale*factor));x=cx-(cx-x)*(next/scale);y=cy-(cy-y)*(next/scale);scale=next;draw()};const entity=(entityKind,id)=>entityKind==='province'?provinces.get(id):entityKind==='state'?states.get(id):regions.get(id);const linked=(province)=>({province,states:province.stateIds.map(id=>states.get(id)),strategicRegions:province.regionIds.map(id=>regions.get(id))});const show=(entityKind,id)=>{const value=entity(entityKind,id);selection.textContent=value?JSON.stringify(entityKind==='province'?linked(value):value,null,2):'No matching record.';if(value?.geometry){const g=value.geometry;x=viewport.clientWidth/2-g.centerX*renderScale*scale;y=viewport.clientHeight/2-g.centerY*renderScale*scale;draw()}};const searchable=[...data.provinces,...data.states,...data.strategicRegions].map(value=>({...value,search:[String(value.id),value.name.key,value.name.displayName,...value.name.values.map(item=>item.value)].join(' ').toLocaleLowerCase('en-US')}));const message=(text)=>Object.assign(document.createElement('span'),{className:'muted',textContent:text});const updateSearch=()=>{const query=search.value.trim().toLocaleLowerCase('en-US'),filter=kind.value;if(!query){results.replaceChildren(message('Search by ID or name.'));return}const matches=searchable.filter(value=>(filter==='all'||value.kind===filter)&&value.search.includes(query)).slice(0,100);results.replaceChildren(...matches.map(value=>{const button=document.createElement('button'),label=document.createElement('span');button.type='button';button.className='result';label.className='kind';label.textContent=value.kind;button.replaceChildren(label,document.createTextNode(' '+value.id+' — '+value.name.displayName));button.onclick=()=>show(value.kind,value.id);return button}),...(matches.length?[]:[message('No matches.')]))};const point=(event)=>{const bounds=viewport.getBoundingClientRect();const imageX=(event.clientX-bounds.left-x)/scale/renderScale,imageY=(event.clientY-bounds.top-y)/scale/renderScale;return{x:Math.floor(imageX),y:Math.floor(imageY)}};const provinceAt=(point)=>{if(!hitContext||point.x<0||point.y<0||point.x>=canvas.width||point.y>=canvas.height)return null;const pixel=hitContext.getImageData(point.x,point.y,1,1).data;const encoded=(pixel[0]<<16)|(pixel[1]<<8)|pixel[2];return encoded===0?null:encoded-1};hit.onload=()=>{canvas.width=hit.naturalWidth;canvas.height=hit.naturalHeight;hitContext=canvas.getContext('2d',{willReadFrequently:true});hitContext.drawImage(hit,0,0)};search.oninput=updateSearch;kind.onchange=updateSearch;document.getElementById('in').onclick=()=>zoom(1.25);document.getElementById('out').onclick=()=>zoom(.8);document.getElementById('fit').onclick=fit;viewport.addEventListener('wheel',event=>{event.preventDefault();const bounds=viewport.getBoundingClientRect();zoom(event.deltaY<0?1.15:.87,event.clientX-bounds.left,event.clientY-bounds.top)},{passive:false});image.addEventListener('pointerdown',event=>{drag=true;moved=false;lastX=event.clientX;lastY=event.clientY;image.setPointerCapture(event.pointerId);image.classList.add('dragging')});image.addEventListener('pointermove',event=>{const p=point(event),provinceId=provinceAt(p),province=provinceId===null?null:provinces.get(provinceId);cursor.textContent='pixel '+p.x+','+p.y+' | map '+p.x+','+(data.height-1-p.y)+(province?' | province '+province.id+' '+province.name.displayName+' | state '+province.stateIds.join(',')+' | region '+province.regionIds.join(','):'');if(!drag)return;const dx=event.clientX-lastX,dy=event.clientY-lastY;if(Math.abs(dx)+Math.abs(dy)>2)moved=true;x+=dx;y+=dy;lastX=event.clientX;lastY=event.clientY;draw()});image.addEventListener('pointerup',event=>{drag=false;image.classList.remove('dragging');if(!moved){const provinceId=provinceAt(point(event));if(provinceId!==null)show('province',provinceId)}});image.onload=fit;window.addEventListener('resize',fit);draw()})();</script></body></html>`;
+}
+function diffHtmlDocument(title, png, json) {
     const escapedTitle = title
         .replaceAll('&', '&amp;')
         .replaceAll('<', '&lt;')
         .replaceAll('>', '&gt;');
     const escapedJson = json.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
-    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapedTitle}</title><style>html{background:#10151b;color:#edf2f7;font:14px system-ui}body{margin:20px}.controls{display:flex;gap:8px;align-items:center;margin:12px 0}button{background:#263241;color:#edf2f7;border:1px solid #526173;border-radius:4px;padding:6px 10px}.viewport{height:70vh;overflow:hidden;border:1px solid #48515c;background:#080b0f;position:relative;touch-action:none}.viewport img{image-rendering:pixelated;transform-origin:0 0;position:absolute;max-width:none;cursor:grab;user-select:none}.viewport img.dragging{cursor:grabbing}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style></head><body><h1>${escapedTitle}</h1><div class="controls"><button id="out" type="button">-</button><button id="reset" type="button">Reset</button><button id="in" type="button">+</button><output id="zoom">100%</output></div><div class="viewport" id="viewport"><img id="map" draggable="false" alt="${escapedTitle}" src="data:image/png;base64,${png.toString('base64')}"></div><details><summary>Render metadata</summary><pre>${escapedJson}</pre></details><script>(()=>{const image=document.getElementById('map'),viewport=document.getElementById('viewport'),label=document.getElementById('zoom');let scale=1,x=0,y=0,drag=false,lastX=0,lastY=0;const draw=()=>{image.style.transform='translate('+x+'px,'+y+'px) scale('+scale+')';label.value=Math.round(scale*100)+'%'};const zoom=(factor,cx=viewport.clientWidth/2,cy=viewport.clientHeight/2)=>{const next=Math.min(16,Math.max(.1,scale*factor));x=cx-(cx-x)*(next/scale);y=cy-(cy-y)*(next/scale);scale=next;draw()};document.getElementById('in').onclick=()=>zoom(1.25);document.getElementById('out').onclick=()=>zoom(.8);document.getElementById('reset').onclick=()=>{scale=1;x=0;y=0;draw()};viewport.addEventListener('wheel',event=>{event.preventDefault();const bounds=viewport.getBoundingClientRect();zoom(event.deltaY<0?1.15:.87,event.clientX-bounds.left,event.clientY-bounds.top)},{passive:false});image.addEventListener('pointerdown',event=>{drag=true;lastX=event.clientX;lastY=event.clientY;image.setPointerCapture(event.pointerId);image.classList.add('dragging')});image.addEventListener('pointermove',event=>{if(!drag)return;x+=event.clientX-lastX;y+=event.clientY-lastY;lastX=event.clientX;lastY=event.clientY;draw()});image.addEventListener('pointerup',()=>{drag=false;image.classList.remove('dragging')});draw()})();</script></body></html>`;
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapedTitle}</title><style>html{background:#10151b;color:#edf2f7;font:14px system-ui}body{margin:20px}.viewport{height:70vh;overflow:auto;border:1px solid #48515c;background:#080b0f}.viewport img{image-rendering:pixelated;max-width:none}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style></head><body><h1>${escapedTitle}</h1><div class="viewport"><img alt="${escapedTitle}" src="data:image/png;base64,${png.toString('base64')}"></div><details><summary>Diff metadata</summary><pre>${escapedJson}</pre></details></body></html>`;
+}
+async function encodeProvinceHitMap(index) {
+    const raster = index.raster;
+    if (raster === undefined)
+        throw new ServiceError('MAP_RENDER_RASTER_MISSING', 'Cannot build a province hit map without a valid province raster');
+    const raw = Buffer.alloc(raster.width * raster.height * 3);
+    for (let offset = 0; offset < raster.provinceIds.length; offset += 1) {
+        const encoded = (raster.provinceIds[offset] ?? -1) + 1;
+        const target = offset * 3;
+        raw[target] = (encoded >> 16) & 255;
+        raw[target + 1] = (encoded >> 8) & 255;
+        raw[target + 2] = encoded & 255;
+    }
+    return sharp(raw, {
+        raw: { width: raster.width, height: raster.height, channels: 3 },
+        limitInputPixels: RENDER_MAX_PIXELS,
+    })
+        .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+        .toBuffer();
 }
 async function encodePng(raw, width, height, scale) {
     assertRenderDimensions(width, height, 'map Sharp source raster');
@@ -481,7 +374,8 @@ export async function renderMap(index, options = {}) {
     const png = await encodePng(raw, raster.width, raster.height, resolved.scale);
     options.signal?.throwIfAborted();
     const json = `${canonicalJson(await renderMetadata(index, resolved, options.signal))}\n`;
-    const html = htmlDocument(`Agent Nudger map - ${resolved.layer}`, png, json);
+    const provinceHitMap = await encodeProvinceHitMap(index);
+    const html = htmlDocument(`HOI4 map - ${resolved.layer}`, png, provinceHitMap, json, resolved.scale);
     return {
         width: outputDimensions.width,
         height: outputDimensions.height,
@@ -734,15 +628,14 @@ export async function renderMapDiff(before, after, options = {}) {
     const semantic = semanticMapDiff(before, after);
     const changedBounds = left.diffBounds(right);
     const metadata = {
-        offline: true,
-        renderer: 'hoi4-agent-tools-agent-nudger-diff',
+        renderer: 'hoi4-agent-tools-map-diff',
         changedBounds: changedBounds ?? null,
         changedProvinceIds: [...changedProvinceIds].sort((a, b) => a - b),
         semantic,
         ...(options.review === undefined ? {} : { review: options.review }),
     };
     const json = `${canonicalJson(metadata)}\n`;
-    const html = htmlDocument('Agent Nudger pixel and semantic diff', png, json);
+    const html = diffHtmlDocument('HOI4 map pixel and semantic diff', png, json);
     return {
         width: outputDimensions.width,
         height: outputDimensions.height,

package/dist/hoi4_agent_tools/map/service.js

@@ -137,6 +137,7 @@ const provinceOperationKinds = new Set([
     'merge_provinces',
     'remove_province',
     'update_province_definition',
+    'renumber_map_entity',
     'add_normal_adjacency',
     'remove_normal_adjacency',
 ]);

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

@@ -2,7 +2,7 @@ import { z } from 'zod/v4';
 import { boundedSourceHashEvidence, publicArtifactLink, } from '../../core/artifacts.js';
 import { canonicalJson, hashCanonical } from '../../core/canonical.js';
 import { emptyServiceResult } from '../../core/result.js';
-import { AgentNudger, allocateMapIdentifiersAsync, exportProvinceGeometryRowRuns, MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT, } from '../../map/index.js';
+import { AgentNudger, allocateMapIdentifiersAsync, buildMapCatalog, exportProvinceGeometryRowRuns, lookupMapCoordinate, MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT, renderMap, searchMapCatalog, } from '../../map/index.js';
 import { workspaceIdSchema } from '../../schemas/common.js';
 import { mapAllocationRequestSchema, mapOperationSchema } from '../../schemas/map.js';
 import { PACKAGE_VERSION } from '../../version.js';
@@ -78,6 +78,9 @@ const mapWorkspaceInspectOutputSchema = strictOperationResultSchema(z
     inspectedStateCount: nonNegativeIntegerSchema,
     inspectedRegionCount: nonNegativeIntegerSchema,
     allocationCount: nonNegativeIntegerSchema,
+    queryMatchCount: nonNegativeIntegerSchema,
+    coordinateMatchCount: nonNegativeIntegerSchema,
+    overviewRendered: z.boolean(),
     provinceGeometryCount: nonNegativeIntegerSchema,
     provinceGeometryPixelCount: nonNegativeIntegerSchema,
     provinceGeometryRowRunCount: nonNegativeIntegerSchema,
@@ -348,7 +351,7 @@ export function registerMapTools(server, engine, context) {
     const nudger = new AgentNudger(engine);
     server.registerTool('hoi4.map_inspect', {
         title: 'Inspect HOI4 map',
-        description: 'Validate the map and write linked inspection evidence. ID selectors return bounded records; provinceIds also export exact row-run geometry.',
+        description: 'Render, validate, search, and click the complete map.',
         inputSchema: z
             .object({
             workspaceId: workspaceIdSchema,
@@ -356,21 +359,47 @@ export function registerMapTools(server, engine, context) {
                 .array(z.number().int().min(0))
                 .max(MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT)
                 .default([])
-                .describe(`Optional exact-geometry selector; exports row runs for at most ${MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT} province IDs`),
+                .describe(`Export row runs for up to ${MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT} province IDs`),
             stateIds: z.array(z.number().int().positive()).max(1_000).default([]),
             regionIds: z.array(z.number().int().positive()).max(1_000).default([]),
+            query: z.string().max(256).optional(),
+            queryLimit: z.number().int().min(1).max(1_000).default(100),
+            coordinates: z
+                .array(z.discriminatedUnion('kind', [
+                z
+                    .object({
+                    kind: z.literal('pixel'),
+                    x: z.number().int().min(0),
+                    y: z.number().int().min(0),
+                })
+                    .strict(),
+                z
+                    .object({
+                    kind: z.literal('map'),
+                    x: z.number(),
+                    z: z.number(),
+                })
+                    .strict(),
+            ]))
+                .max(100)
+                .default([]),
+            includeOverview: z.boolean().default(true),
             allocationRequests: z.array(mapAllocationRequestSchema).max(100).default([]),
         })
             .strict(),
         outputSchema: mapWorkspaceInspectOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId: requestedWorkspaceId, provinceIds, stateIds, regionIds, allocationRequests }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, provinceIds, stateIds, regionIds, query, queryLimit, coordinates, includeOverview, allocationRequests, }, extra) => {
         const workspaceId = await resolveServerWorkspaceId(engine, context, requestedWorkspaceId, extra.signal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Inspecting and validating the map');
             const { snapshot, validation } = await nudger.validate(workspaceId, context.principal, progress.signal);
             const sharedRevision = snapshot.revision;
+            const catalog = buildMapCatalog(snapshot.index);
+            const queryMatches = query === undefined ? [] : searchMapCatalog(catalog, query, queryLimit);
+            const coordinateMatches = coordinates.map((coordinate) => lookupMapCoordinate(snapshot.index, coordinate));
+            const overviewRendered = includeOverview && snapshot.index.raster !== undefined;
             const selected = selectedMapEntities(snapshot, provinceIds, stateIds, regionIds);
             const provinceGeometry = provinceIds.length === 0
                 ? undefined
@@ -387,7 +416,7 @@ export function registerMapTools(server, engine, context) {
             const inspectionProvenance = {
                 kind: 'map-inspect',
                 toolVersion: PACKAGE_VERSION,
-                schemaVersion: 'map-inspect.v1',
+                schemaVersion: 'map-inspect.v2',
                 sourceHashes: sourceEvidence.bounded.sourceHashes,
                 metadata: {
                     sharedRevision,
@@ -399,7 +428,7 @@ export function registerMapTools(server, engine, context) {
                     name: `map-inspect.${snapshot.revision.slice(0, 16)}.json`,
                     mimeType: 'application/json',
                     content: `${canonicalJson({
-                        schemaVersion: 1,
+                        schemaVersion: 2,
                         revision: snapshot.revision,
                         sharedRevision,
                         dimensions: snapshot.index.raster === undefined
@@ -420,15 +449,59 @@ export function registerMapTools(server, engine, context) {
                             ports: snapshot.index.ports.length,
                             locators: snapshot.index.entityLocators.length,
                         },
+                        catalog,
+                        query: query ?? null,
+                        queryMatches,
+                        coordinateMatches,
                         selected,
                         allocationPreviews,
                         validation,
                         sourceHashes: sourceEvidence.complete,
                     })}\n`,
                     provenance: inspectionProvenance,
-                    description: 'Complete map inspection, validation, selected records, and allocation previews',
+                    description: 'Complete searchable map catalog, inspection, validation, selected records, and allocation previews',
                 },
             ];
+            if (overviewRendered) {
+                const overviewLayer = 'state';
+                const overviewOverlays = [
+                    'coastlines',
+                    'ports',
+                    'victory-points',
+                    'supply-nodes',
+                    'railways',
+                ];
+                const overview = await renderMap(snapshot.index, {
+                    layer: overviewLayer,
+                    overlays: overviewOverlays,
+                    signal: progress.signal,
+                });
+                const overviewProvenance = {
+                    kind: 'map-inspect-overview',
+                    toolVersion: PACKAGE_VERSION,
+                    schemaVersion: 'map-inspect-overview.v1',
+                    sourceHashes: sourceEvidence.bounded.sourceHashes,
+                    renderProfile: {
+                        layer: overviewLayer,
+                        overlays: [...new Set(overviewOverlays)].sort(),
+                        scale: 1,
+                    },
+                    metadata: { sourceHashInventory: sourceEvidence.bounded.inventory },
+                };
+                artifactWrites.push({
+                    name: `map-overview.${snapshot.revision.slice(0, 16)}.png`,
+                    mimeType: 'image/png',
+                    content: overview.png,
+                    provenance: overviewProvenance,
+                    description: 'Complete rendered map overview',
+                }, {
+                    name: `map-overview.${snapshot.revision.slice(0, 16)}.html`,
+                    mimeType: 'text/html',
+                    content: overview.html,
+                    provenance: overviewProvenance,
+                    description: 'Searchable and clickable full-map navigator with exact IDs, names, coordinates, and linked records',
+                });
+            }
             if (provinceGeometry !== undefined) {
                 const { width, height, requestedProvinceIds, unknownProvinceIds, missingGeometryProvinceIds, pixelCount, rowRunCount, provinces, } = provinceGeometry;
                 const selectorHash = hashCanonical(requestedProvinceIds).slice(0, 16);
@@ -480,6 +553,9 @@ export function registerMapTools(server, engine, context) {
                 inspectedStateCount: selected.states.length,
                 inspectedRegionCount: selected.regions.length,
                 allocationCount: allocationPreviews.length,
+                queryMatchCount: queryMatches.length,
+                coordinateMatchCount: coordinateMatches.length,
+                overviewRendered,
                 provinceGeometryCount: provinceGeometry?.provinces.length ?? 0,
                 provinceGeometryPixelCount: provinceGeometry?.pixelCount ?? 0,
                 provinceGeometryRowRunCount: provinceGeometry?.rowRunCount ?? 0,
@@ -500,7 +576,7 @@ export function registerMapTools(server, engine, context) {
     });
     server.registerTool('hoi4.map_render', {
         title: 'Render map inspection artifacts',
-        description: 'Render deterministic offline map artifacts for one layer and bounded overlays.',
+        description: 'Render searchable full-map PNG, JSON, and HTML.',
         inputSchema: z
             .object({
             workspaceId: workspaceIdSchema,
@@ -542,7 +618,7 @@ export function registerMapTools(server, engine, context) {
     });
     server.registerTool('hoi4.map_rewrite', {
         title: 'Create or clean up map content',
-        description: 'Apply validated declarative map operations in one call and return linked pixel and semantic evidence.',
+        description: 'Apply map creation, edits, and ID swaps with visual and semantic evidence.',
         inputSchema: z
             .object({
             workspaceId: workspaceIdSchema,

package/dist/hoi4_agent_tools/schemas/map.js

@@ -133,6 +133,22 @@ const provinceGeometrySchema = z.discriminatedUnion('kind', [
             .describe(`Exact coordinates to recolor; at most ${MAP_SELECTED_PIXEL_LIMIT} pixels per operation`),
     })
         .strict(),
+    z
+        .object({
+        kind: z.literal('rectangle'),
+        origin: pointSchema,
+        width: z.number().int().positive().max(RENDER_MAX_DIMENSION),
+        height: z.number().int().positive().max(RENDER_MAX_DIMENSION),
+    })
+        .strict()
+        .superRefine((value, context) => {
+        if (value.width * value.height > MAP_SELECTED_PIXEL_LIMIT)
+            context.addIssue({
+                code: 'custom',
+                path: ['width'],
+                message: `Rectangle selects more than ${MAP_SELECTED_PIXEL_LIMIT} pixels`,
+            });
+    }),
     z
         .object({
         kind: z.literal('mask'),
@@ -262,6 +278,24 @@ const splitStateOperation = (kind) => z
     distribution: splitStateDistributionSchema,
 })
     .strict();
+const createStateOperation = z
+    .object({
+    ...operationBase,
+    kind: z.literal('create_state'),
+    sourceStateId: stateId.optional(),
+    stateId: stateId.optional(),
+    provinceIds: z.array(provinceId).min(1).max(100_000),
+    name: z.string().min(1).max(1000).optional(),
+    displayName: z.string().min(1).max(100_000).optional(),
+    fileName: z.string().max(255).optional(),
+    localisation: stateLocalisationSchema.optional(),
+    distribution: z.union([z.literal('proportional'), splitStateDistributionSchema]).optional(),
+})
+    .strict()
+    .refine((value) => value.name !== undefined || value.displayName !== undefined, {
+    message: 'create_state requires name or displayName',
+    path: ['displayName'],
+});
 const splitProvinceOperation = (kind) => z
     .object({
     ...operationBase,
@@ -273,6 +307,19 @@ const splitProvinceOperation = (kind) => z
     distribution: splitProvinceDistributionSchema,
 })
     .strict();
+const createProvinceOperation = z
+    .object({
+    ...operationBase,
+    kind: z.literal('create_province'),
+    sourceProvinceId: provinceId,
+    provinceId: provinceId.optional(),
+    geometry: provinceGeometrySchema,
+    definition: provinceDefinitionSchema.optional(),
+    distribution: z
+        .union([z.literal('inherit-source'), splitProvinceDistributionSchema])
+        .optional(),
+})
+    .strict();
 const occurrenceSchema = z.number().int().min(0).optional();
 export const mapOperationSchema = z.discriminatedUnion('kind', [
     z
@@ -354,7 +401,7 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
     })
         .strict(),
     splitStateOperation('split_state'),
-    splitStateOperation('create_state'),
+    createStateOperation,
     z
         .object({
         ...operationBase,
@@ -365,7 +412,7 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
     })
         .strict(),
     splitProvinceOperation('split_province'),
-    splitProvinceOperation('create_province'),
+    createProvinceOperation,
     z
         .object({
         ...operationBase,
@@ -405,6 +452,26 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         distribution: z.literal('move-membership'),
     })
         .strict(),
+    z
+        .object({
+        ...operationBase,
+        kind: z.literal('renumber_map_entity'),
+        entity: z.enum(['province', 'state', 'strategic-region']),
+        fromId: z.number().int().min(0),
+        toId: z.number().int().min(0),
+        collision: z.enum(['swap', 'reject']).default('swap'),
+        renameLocalisation: z.boolean().default(true),
+    })
+        .strict()
+        .superRefine((value, context) => {
+        if (value.entity !== 'province' && (value.fromId === 0 || value.toId === 0)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['fromId'],
+                message: 'State and strategic-region IDs must be positive',
+            });
+        }
+    }),
     z
         .object({
         ...operationBase,

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