hoi4-agent-tools 4.0.4 → 4.1.0

package/dist/hoi4_agent_tools/gui/layout.js

@@ -629,11 +629,12 @@ function explicitElementVisibility(definition, scenario, rowValues) {
         visibilityValue(scripted));
 }
 /** Source visibility: `visible` and `show` mean shown when true, `hide` and `hidden` when false. */
-function declaredVisibility(attributes) {
+function declaredVisibility(attributes, fallback = true) {
     const visible = scalarBoolean(property(attributes, 'visible', 'show'));
     if (visible !== undefined)
         return visible;
-    return !(scalarBoolean(property(attributes, 'hide', 'hidden')) ?? false);
+    const hidden = scalarBoolean(property(attributes, 'hide', 'hidden'));
+    return hidden === undefined ? fallback : !hidden;
 }
 function clippedByChain(chain) {
     let result;
@@ -694,7 +695,7 @@ function refreshSceneClips(context) {
     }
 }
 function attachedScrollbars(definition, context) {
-    if (!/^(?:containerwindowtype|windowtype)$/iu.test(definition.elementType))
+    if (!/^(?:containerwindowtype|windowtype|expandedwindow)$/iu.test(definition.elementType))
         return [];
     const result = [];
     const add = (candidate, horizontal, reference) => {
@@ -718,8 +719,10 @@ function attachedScrollbars(definition, context) {
     for (const horizontal of [false, true]) {
         const name = scalarString(property(definition.attributes, horizontal ? 'horizontalScrollbar' : 'verticalScrollbar'));
         if (name !== undefined) {
-            const candidate = context.elementsByName.get(name);
-            add(candidate?.parentId === undefined ? candidate : undefined, horizontal, name);
+            const candidate = context.elementsByNameCandidates
+                .get(name)
+                ?.find((element) => element.parentId === undefined);
+            add(candidate, horizontal, name);
         }
     }
     for (const id of definition.childIds) {
@@ -1218,10 +1221,13 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const clipChain = inheritedClipChain ?? (inheritedClip === undefined ? [] : [inheritedClip]);
     const localScale = scalarNumber(property(definition.attributes, 'scale'), 1) ?? 1;
     const scale = parentScale * localScale;
-    const shownPosition = depth === 0 ? objectProperty(property(definition.attributes, 'show_position')) : undefined;
+    const expandedWindow = definition.elementType.toLowerCase() === 'expandedwindow';
+    const shownPosition = depth === 0 || expandedWindow
+        ? objectProperty(property(definition.attributes, 'show_position'))
+        : undefined;
     const position = shownPosition ?? objectProperty(property(definition.attributes, 'position'));
     if (shownPosition !== undefined) {
-        addFidelity(fidelity, 'modelled', 'window_show_position', 'The requested root window uses its declared settled show position.', definition);
+        addFidelity(fidelity, 'modelled', 'window_show_position', 'The requested window uses its declared settled show position.', definition);
     }
     const size = objectProperty(property(definition.attributes, 'size'));
     const scriptedX = rowValues?.[`${definition.name}.x`] ??
@@ -1277,13 +1283,19 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
         width = Math.max(0, parentRect.width - localX + width);
     if (height < 0)
         height = Math.max(0, parentRect.height - localY + height);
-    const explicitlyVisible = explicitElementVisibility(definition, scenario, rowValues);
+    const explicitlyVisible = explicitElementVisibility(definition, scenario, rowValues) ??
+        context.nativeVisibility.get(definition.id);
     const unresolvedVisibilityReason = context.unresolvedElementVisibility.get(definition.name);
     const parentSceneElement = parentInstanceId === undefined ? undefined : context.instancesById.get(parentInstanceId);
     const parentUnresolvedVisibility = parentSceneElement?.visibilityStatus === 'unresolved'
         ? parentSceneElement.visibilityStatusReason
         : undefined;
-    const sourceVisible = declaredVisibility(definition.attributes);
+    const dropdown = definition.parentId === undefined ? undefined : context.elementsById.get(definition.parentId);
+    const sourceVisible = declaredVisibility(definition.attributes, !expandedWindow ||
+        depth === 0 ||
+        visibilityValue(rowValues?.[`${dropdown?.name}.expanded`] ?? scenario.values[`${dropdown?.name}.expanded`]) === true);
+    if (expandedWindow)
+        addFidelity(fidelity, 'modelled', 'native_dropdown', 'Dropdown expansion is closed by default; bind <dropdown>.expanded or explicit panel visibility to show its settled position.', definition);
     const resolveVisibleAppearance = inheritedVisible && (explicitlyVisible ?? sourceVisible);
     const scriptedEnabled = rowValues?.[`${definition.name}.enabled`] ??
         scenario.values[`${definition.name}.enabled`] ??
@@ -1619,12 +1631,13 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     else if (origoAxes.vertical === 'bottom')
         y -= height;
     const unclippedRect = { x, y, width: Math.max(0, width), height: Math.max(0, height) };
-    const ownClipping = scalarBoolean(property(definition.attributes, 'clipping')) ??
-        (backgrounds.length > 0 && /(?:containerwindow|windowtype)/iu.test(definition.elementType));
     let scrollbars = attachedScrollbars(definition, context);
-    if (scrollbars.length > 0 && (!ownClipping || backgrounds.length === 0)) {
-        diagnostics.push(diagnostic('GUI_SCROLLBAR_CONTAINER_BOUNDARY_MISSING', 'warning', `Container ${definition.name} needs a background and clipping for attached scrolling.`, definition));
-        addFidelity(fidelity, 'unsupported', 'attached_scrollbar', 'The container has no active clipped background boundary.', definition);
+    const ownClipping = scalarBoolean(property(definition.attributes, 'clipping')) ??
+        ((backgrounds.length > 0 || scrollbars.length > 0) &&
+            /(?:containerwindow|windowtype|expandedwindow)/iu.test(definition.elementType));
+    if (scrollbars.length > 0 && (!ownClipping || width <= 0 || height <= 0)) {
+        diagnostics.push(diagnostic('GUI_SCROLLBAR_CONTAINER_BOUNDARY_MISSING', 'warning', `Container ${definition.name} needs a positive-sized clipping boundary for attached scrolling.`, definition));
+        addFidelity(fidelity, 'unsupported', 'attached_scrollbar', 'The container has no active clipping boundary.', definition);
         scrollbars = [];
     }
     const margin = scrollbars.length === 0 ? undefined : objectProperty(property(definition.attributes, 'margin'));
@@ -1835,10 +1848,12 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const childDefinitions = await scrollbarChildren(definition, definition.childIds
         .map((id) => context.elementsById.get(id))
         .filter((element) => element !== undefined)
-        .filter((element) => !/^(?:containerwindowtype|windowtype)$/iu.test(definition.elementType) ||
+        .filter((element) => !/^(?:containerwindowtype|windowtype|expandedwindow)$/iu.test(definition.elementType) ||
         element.elementType.toLowerCase() !== 'extendedscrollbartype')
-        .sort((left, right) => (scalarNumber(property(left.attributes, 'priority'), 0) ?? 0) -
-        (scalarNumber(property(right.attributes, 'priority'), 0) ?? 0) ||
+        .sort((left, right) => Number(context.nativeForeground.has(left.id)) -
+        Number(context.nativeForeground.has(right.id)) ||
+        (scalarNumber(property(left.attributes, 'priority'), 0) ?? 0) -
+            (scalarNumber(property(right.attributes, 'priority'), 0) ?? 0) ||
         left.definitionOrder - right.definitionOrder), unclippedRect, scale, context, rowValues);
     const rowList = rowValues?.[`${definition.name}.list`];
     let rows = (typeof rowList === 'string' ? scenario.lists[rowList] : undefined) ??
@@ -1908,7 +1923,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
                     ...(slotWidth === undefined ? {} : { width: slotWidth }),
                     ...(slotHeight === undefined ? {} : { height: slotHeight }),
                 };
-                await layoutElement(child, shiftedParent, childClip, scale, depth + 1, context, rowSuffix(index), index, row, instanceId, origo, resolveVisibleAppearance, childClipChain);
+                await layoutElement(child, shiftedParent, childClip, scale, depth + 1, context, rowSuffix(index), index, row, instanceId, 'upper_left', resolveVisibleAppearance, childClipChain);
                 const rendered = context.instancesById.get(`${child.id}${rowSuffix(index)}`);
                 rowHeight = Math.max(rowHeight, rendered?.unclippedRect.height ?? 0);
             }
@@ -1960,7 +1975,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
                 ...(slotWidth === undefined ? {} : { width: slotWidth }),
                 ...(slotHeight === undefined ? {} : { height: slotHeight }),
             };
-            await layoutElement(template, shiftedParent, childClip, scale, depth + 1, context, rowSuffix(index), index, row, instanceId, origo, resolveVisibleAppearance, childClipChain);
+            await layoutElement(template, shiftedParent, childClip, scale, depth + 1, context, rowSuffix(index), index, row, instanceId, 'upper_left', resolveVisibleAppearance, childClipChain);
             const rendered = context.instancesById.get(`${template.id}${rowSuffix(index)}`);
             rowY += Math.max(slotHeight ?? 0, rendered?.unclippedRect.height ?? 0) + spacingY;
             renderedRows += 1;
@@ -1970,7 +1985,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     else {
         for (const child of childDefinitions) {
             context.work.spend('nested child expansion');
-            await layoutElement(child, childParentRect, childClip, scale, depth + 1, context, instanceSuffix, rowIndex, rowValues, instanceId, origo, resolveVisibleAppearance, childClipChain);
+            await layoutElement(child, childParentRect, childClip, scale, depth + 1, context, instanceSuffix, rowIndex, rowValues, instanceId, 'upper_left', resolveVisibleAppearance, childClipChain);
         }
     }
     const childOutput = context.output.slice(firstChildOutput);
@@ -2195,10 +2210,14 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     if (native !== undefined) {
         for (const note of native.notes)
             addFidelity(fidelity, 'modelled', 'native_window_state', note);
-        const { sources } = native.state;
-        if (native.state.tag === undefined ||
-            sources.faction === 'default' ||
-            sources.balanceOfPower === 'default')
+        for (const note of native.approximations ?? [])
+            addFidelity(fidelity, 'approximated', 'native_window_state', note);
+        const sources = native.state?.sources;
+        if (native.state !== undefined &&
+            sources !== undefined &&
+            (native.state.tag === undefined ||
+                sources.faction === 'default' ||
+                sources.balanceOfPower === 'default'))
             addFidelity(fidelity, 'approximated', 'native_window_state', native.state.tag === undefined
                 ? 'The scenario names no country, so the window shows the state of a country in no faction and without a balance of power; set country.tag or the country faction, balanceOfPower and ideology facts.'
                 : `No history for ${native.state.tag} was available, so its faction and balance of power default to none; set country.faction, country.balanceOfPower and country.ideology to override.`);
@@ -2211,7 +2230,6 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
             ...scenario.values,
         },
         visibility: {
-            ...(native?.visibility ?? {}),
             ...scriptedWindowVisibility,
             ...constantElementVisibility,
             ...scenario.visibility,
@@ -2229,6 +2247,24 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
         elementsByNameCandidates.set(element.name, candidates);
     }
     const context = {
+        nativeForeground: new Set(graph.elements
+            .filter((element) => element.parentId === root.id && native?.foreground?.includes(element.name))
+            .map(({ id }) => id)),
+        nativeVisibility: new Map(graph.elements.flatMap((element) => {
+            const visible = native?.visibility[element.name];
+            if (visible === undefined)
+                return [];
+            // The designer reuses names (including division_title) inside selector panels.
+            // Its branch decisions apply to root controls, not identically named descendants.
+            if (windowName === 'countrydivisiondesignerview' && element.parentId !== root.id) {
+                const parent = element.parentId === undefined ? undefined : elementsById.get(element.parentId);
+                if (element.name !== 'hq_badge' ||
+                    parent?.name !== 'template_emblem_slot' ||
+                    parent.parentId !== root.id)
+                    return [];
+            }
+            return [[element.id, visible]];
+        })),
         graph,
         scenario: layoutScenario,
         catalog,

package/dist/hoi4_agent_tools/gui/native-state.js

@@ -205,13 +205,52 @@ export function resolveNativeCountryState(scenario, files) {
 }
 /** Whether any native decision can apply to this window, so the country state is worth resolving. */
 export function windowHasNativeState(windowName, elementNames) {
-    return (NATIVE_BRANCHES[windowName] !== undefined ||
+    return (windowName === 'countrydivisiondesignerview' ||
+        NATIVE_BRANCHES[windowName] !== undefined ||
         Object.keys(IDEOLOGY_FRAME_ICONS).some((name) => elementNames.has(name)));
 }
 /** The engine-selected branches and frames for a scene, below any explicit scenario input. */
 export function nativeWindowState(windowName, elementNames, scenario, files) {
     if (!windowHasNativeState(windowName, elementNames))
         return undefined;
+    if (windowName === 'countrydivisiondesignerview') {
+        const hq = scenario.values['countrydivisiondesignerview.hq'] === true;
+        const panel = scenario.values['countrydivisiondesignerview.panel'];
+        const visibility = {};
+        for (const name of ['hq_overlay_images', 'subunits_hq', 'hq_view', 'hq_title', 'hq_badge'])
+            if (elementNames.has(name))
+                visibility[name] = hq;
+        for (const name of [
+            'subunits',
+            'non_hq_view',
+            'division_title',
+            'division_composition_label',
+            'combat_width_view',
+        ])
+            if (elementNames.has(name))
+                visibility[name] = !hq;
+        const selectors = [
+            'designerregimentswindow',
+            'division_equipment_view',
+            'div_templ_custom_icon_view',
+            'div_template_select_model',
+            'niche_icon_selector',
+        ];
+        for (const name of selectors)
+            if (elementNames.has(name))
+                visibility[name] = panel === name;
+        return {
+            visibility,
+            values: {},
+            foreground: selectors,
+            notes: [
+                `Division designer uses the ${hq ? 'HQ' : 'division'} branch and only the explicitly selected native selector panel.`,
+            ],
+            approximations: [
+                'Native division state is a preview convention: defaults to a division with selectors closed. Set values countrydivisiondesignerview.hq and countrydivisiondesignerview.panel, or explicit element visibility. Engine-populated rows and statistics require scenario bindings.',
+            ],
+        };
+    }
     const state = resolveNativeCountryState(scenario, files);
     const visibility = {};
     const values = {};

package/dist/hoi4_agent_tools/gui/source-graph.js

@@ -119,7 +119,7 @@ export function guiElementAttributeFidelity(key, elementType) {
     if (elementType?.toLowerCase() === 'extendedscrollbartype' &&
         ['horizontal', 'slider', 'track', 'decreaseButton', 'increaseButton'].some((candidate) => candidate.toLowerCase() === key.toLowerCase()))
         return 'modelled';
-    if (/^(?:containerwindowtype|windowtype)$/iu.test(elementType ?? '') &&
+    if (/^(?:containerwindowtype|windowtype|expandedwindow)$/iu.test(elementType ?? '') &&
         ['verticalScrollbar', 'horizontalScrollbar', 'autohide_scrollbars', 'margin'].some((candidate) => candidate.toLowerCase() === key.toLowerCase()))
         return 'structural';
     if (elementType?.toLowerCase() === 'scrollbartype' &&
@@ -298,9 +298,12 @@ function nestedSizeFrom(block, key) {
 function raw(document, node) {
     return document.text.slice(node.start, node.end);
 }
-function isGuiElement(assignment) {
+function isGuiElement(assignment, parentType) {
     if (assignment.value.type !== 'block')
         return false;
+    if (parentType?.toLowerCase() === 'dropdownboxtype' &&
+        /^(?:expandedwindow|expandbutton)$/iu.test(assignment.key.value))
+        return true;
     if (explicitGuiElementTypes.has(assignment.key.value.toLowerCase()))
         return true;
     return (/type$/iu.test(assignment.key.value) && firstScalar(assignment.value, 'name') !== undefined);
@@ -363,11 +366,11 @@ function indexGuiElements(document, file, fileNodeId, nodes, edges, elements) {
     const constants = constantsFor(document);
     const firstFileElement = elements.length;
     let order = 0;
-    const walk = (block, parentId) => {
+    const walk = (block, parentId, parentType) => {
         for (const assignment of assignments(block)) {
             if (assignment.value.type !== 'block')
                 continue;
-            if (isGuiElement(assignment)) {
+            if (isGuiElement(assignment, parentType)) {
                 const name = firstScalar(assignment.value, 'name')?.value;
                 if (name === undefined)
                     continue;
@@ -386,7 +389,7 @@ function indexGuiElements(document, file, fileNodeId, nodes, edges, elements) {
                     childIds: [],
                     attributes: attributes,
                     unsupportedAttributes: assignments(assignment.value)
-                        .filter((child) => !isGuiElement(child))
+                        .filter((child) => !isGuiElement(child, assignment.key.value))
                         .map(({ key }) => key.value)
                         .filter((key) => guiElementAttributeFidelity(key, assignment.key.value) === 'unsupported')
                         .sort((a, b) => compareCodeUnits(a, b)),
@@ -409,7 +412,7 @@ function indexGuiElements(document, file, fileNodeId, nodes, edges, elements) {
                 addEdge(edges, 'contains', parentId ?? fileNodeId, id, true, {}, element.location);
                 if (parentId !== undefined)
                     addEdge(edges, 'parent', id, parentId, true, {}, element.location);
-                walk(assignment.value, id);
+                walk(assignment.value, id, assignment.key.value);
             }
             else {
                 walk(assignment.value, parentId);

package/dist/hoi4_agent_tools/gui/studio.js

@@ -1048,7 +1048,10 @@ export class ScriptedGuiStudio {
         const requiredNames = new Set([windowName, ...additionalTemplateNames]);
         for (const element of selectedLayoutElements)
             collectNamedAttributes(element.attributes, new Set(['verticalScrollbar', 'horizontalScrollbar', 'scrollbarType', 'scrollbartype']), requiredNames);
-        const availableNames = new Set(layoutGraph.elements.map(({ name }) => name));
+        // Scrollbar and row references name public templates, not private controls with the same name.
+        const availableNames = new Set(layoutGraph.elements.filter(({ parentId }) => parentId === undefined).map(({ name }) => name));
+        if (layoutGraph.elements.some(({ name }) => name === windowName))
+            availableNames.add(windowName);
         if ([...requiredNames].some((name) => !availableNames.has(name))) {
             const gameLayouts = await this.scanner.scan(workspace, {
                 patterns: layoutPatterns,

package/dist/hoi4_agent_tools/map/derived.js

@@ -136,9 +136,9 @@ function coastPoint(raster, shape, isSea) {
             [0, 1],
             [0, -1],
         ]) {
-            const nx = x + dx;
+            const nx = (x + dx + raster.width) % raster.width;
             const ny = y + dy;
-            if (nx < 0 || ny < 0 || nx >= raster.width || ny >= raster.height)
+            if (ny < 0 || ny >= raster.height)
                 continue;
             const other = raster.provinceIds[ny * raster.width + nx];
             if (other < 0 || !isSea(other))
@@ -154,6 +154,19 @@ function coastPoint(raster, shape, isSea) {
     const middle = points[Math.floor(points.length / 2)];
     return { ...middle, sea };
 }
+/** A sea pixel next to the landing province, staying inside narrow inlets and map edges. */
+function floatingHarborPoint(raster, coast) {
+    for (const distance of [2, 1]) {
+        const x = (coast.x + coast.dx * distance + raster.width) % raster.width;
+        const y = coast.y + coast.dy * distance;
+        if (y < 0 || y >= raster.height)
+            continue;
+        // Keep the same sea association selected from the real coastal contact.
+        if (raster.provinceIds[y * raster.width + x] === coast.sea)
+            return { x, y };
+    }
+    throw new ServiceError('MAP_FLOATING_HARBOR_WATER_UNAVAILABLE', 'The selected coastal contact has no adjacent sea pixel for a floating harbor');
+}
 function rotationFor(dx, dy) {
     // Bitmap y grows downward; map z grows upward.
     return Math.atan2(-dy, dx);
@@ -315,9 +328,8 @@ function planBuildingPositions(index, request) {
                         continue;
                     for (let copy = 0; copy < perOwner && produced < wanted - have; copy += 1, produced += 1) {
                         const floating = slot.name === 'floating_harbor';
-                        // A floating harbour sits on the water two pixels out and names its land province.
-                        const x = floating ? coast.x + coast.dx * 2 : coast.x;
-                        const y = floating ? coast.y + coast.dy * 2 : coast.y;
+                        // Prefer two pixels offshore, with a verified adjacent-water fallback.
+                        const { x, y } = floating ? floatingHarborPoint(raster, coast) : coast;
                         added.push([
                             state.id,
                             slot.name,
@@ -350,7 +362,10 @@ function planBuildingPositions(index, request) {
     }
     return {
         relativePath: document?.file.relativePath ?? `${mapRoot(index)}/buildings.txt`,
-        content: rewriteLines(document, drop, added),
+        // The native building-position reader treats a trailing newline as an empty CSV record.
+        content: Buffer.from(rewriteLines(document, drop, added)
+            .toString('utf8')
+            .replace(/\r?\n$/u, ''), 'utf8'),
     };
 }
 function planUnitPositions(index, request) {

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

@@ -4,7 +4,7 @@ import { errorResult, toolResult } from '../core/operation-result.js';
 import { ServiceError } from '../core/result.js';
 import { MAP_VIEW_FIELDS, mapInspectRequestSchema, mapRewriteRequestSchema, } from '../schemas/map-requests.js';
 import { AgentNudger } from './service.js';
-import { inspectMap, completeMapRewrite, normalizeMapInspectRequest, normalizeMapRenderRequest, normalizeMapRewriteRequest, prepareMapRewrite, renderMapView, } from './tool-operations.js';
+import { inspectMap, completeMapRewrite, normalizeMapInspectRequest, normalizeMapRenderRequest, normalizeMapRewriteRequest, prepareMapRewrite, previewMapRewrite, renderMapView, } from './tool-operations.js';
 const wireResult = z.record(z.string(), z.json());
 /** Registers read-only map operations without invoking transport handlers. */
 export function registerMapJobs(operations, engine) {
@@ -54,12 +54,18 @@ export function registerMapJobs(operations, engine) {
             throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');
         const release = lifetime.begin();
         try {
-            return await prepareMapRewrite(nudger, normalizeMapRewriteRequest(input), {
+            const operationContext = {
                 workspaceId: context.workspaceId,
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: context.signal,
                 progress: (completed, total, message) => context.progress({ completed, total, message }),
-            });
+            };
+            const normalized = normalizeMapRewriteRequest(input);
+            if (normalized.preview)
+                return {
+                    readOnlyPreview: wireResult.parse(JSON.parse(JSON.stringify(toolResult(await previewMapRewrite(nudger, normalized, operationContext))))),
+                };
+            return await prepareMapRewrite(nudger, normalized, operationContext);
         }
         finally {
             release();

package/dist/hoi4_agent_tools/map/operations.js

@@ -9,6 +9,8 @@ import { derivedStateCapital, encodeTextDocument, LEVEL_STATE_BUILDINGS, MapWork
 import { planReferenceRemap, ReferenceRemapError } from './references.js';
 import { generateWorld } from './world.js';
 import { planMapPositions, planSupplyRebuild } from './derived.js';
+import { buildWorldContext } from './world-context.js';
+import { reconcileWorldOutputs } from './world-outputs.js';
 function* cancellationCheckpoint(signal, iteration = 0, stride = 1) {
     if (iteration % stride !== 0)
         return;
@@ -3250,6 +3252,14 @@ export const WORLD_REPLACED_ROOTS = [
     'map/supplyareas',
     'common/bookmarks',
 ];
+const STARTING_SCENARIO_REPLACED_ROOTS = [
+    'common/on_actions',
+    'common/ai_areas',
+    'common/ai_strategy_plans',
+    'common/ai_strategy',
+    'common/decisions',
+    'events',
+];
 /** Add replace_path lines to descriptor.mod, creating a minimal descriptor when none exists. */
 function descriptorWithReplacePaths(index, roots) {
     const existing = index.sourceFiles.find((file) => file.rootKind === 'mod' && normalizeRelative(file.relativePath) === 'descriptor.mod');
@@ -3262,36 +3272,56 @@ function descriptorWithReplacePaths(index, roots) {
     const body = textValue.endsWith('\n') ? textValue : `${textValue}${newline}`;
     return Buffer.from(`${body}${missing.map((root) => `replace_path="${root}"`).join(newline)}${missing.length > 0 ? newline : ''}`, 'utf8');
 }
-function applyCreateWorld(base, changes, operation) {
+function applyCreateWorld(base, changes, operation, context) {
+    const reference = context.referenceWorlds?.get(operation.id);
+    if (operation.reference !== undefined && reference === undefined)
+        throw new ServiceError('MAP_REFERENCE_NOT_PREPARED', 'Reference worlds must be prepared by the authorized workspace service');
     const mapRoot = base.sourceRoots.map[0] ?? 'map';
+    const startingScenario = operation.startingScenario ?? reference !== undefined;
     const world = generateWorld({
-        width: operation.width ?? 1_024,
-        height: operation.height ?? 512,
+        startingScenario,
+        ...(operation.worldName === undefined ? {} : { worldName: operation.worldName }),
+        width: operation.width ?? reference?.surface.width ?? 1_024,
+        height: operation.height ?? reference?.surface.height ?? 512,
         seed: operation.seed ?? 1,
         landCoverage: operation.landCoverage ?? 0.35,
         continents: operation.continents ?? 3,
         ...(operation.landPolygons === undefined ? {} : { landPolygons: operation.landPolygons }),
         landProvincePixels: operation.landProvincePixels ?? 400,
         seaProvincePixels: operation.seaProvincePixels ?? 2_500,
-        provincesPerState: operation.provincesPerState ?? 5,
-        landProvincesPerRegion: operation.landProvincesPerRegion ?? 25,
-        seaProvincesPerRegion: operation.seaProvincesPerRegion ?? 10,
-        countries: operation.countries,
+        provincesPerState: operation.provincesPerState ?? (reference === undefined ? 5 : 12),
+        landProvincesPerRegion: operation.landProvincesPerRegion ?? (reference === undefined ? 25 : 60),
+        seaProvincesPerRegion: operation.seaProvincesPerRegion ?? (reference === undefined ? 10 : 30),
+        countries: operation.countries ??
+            reference?.countries ?? [
+            { tag: 'X01', name: 'Aster' },
+            { tag: 'X02', name: 'Brum' },
+            { tag: 'X03', name: 'Corvel' },
+            { tag: 'X04', name: 'Doran' },
+        ],
+        ...(reference === undefined
+            ? {}
+            : {
+                referenceSurface: reference.surface,
+                referenceCities: reference.cities,
+                referenceLabels: reference.labels,
+            }),
         ...(operation.continentNames === undefined
             ? {}
             : { continentNames: operation.continentNames }),
         startDate: operation.startDate ?? '1936.1.1',
-        rivers: operation.rivers ?? 8,
-    }, {
-        palettes: {},
-        mapRoot,
-        statesRoot: base.sourceRoots.states[0] ?? 'history/states',
-        localisationRoot: base.sourceRoots.localisation[0] ?? 'localisation',
-    });
-    const roots = operation.replaceBaseGame === false ? [] : [...WORLD_REPLACED_ROOTS];
+        rivers: operation.rivers ?? (reference === undefined ? 8 : 80),
+    }, buildWorldContext(base));
+    const roots = operation.replaceBaseGame === false
+        ? []
+        : [...WORLD_REPLACED_ROOTS, ...(startingScenario ? STARTING_SCENARIO_REPLACED_ROOTS : [])];
     replacedRootsByPlan.set(changes, roots);
     for (const file of world.files)
         addChange(changes, file.relativePath, file.content, operation.id, file.mediaType);
+    // Remove only unchanged outputs recorded by a previous generation, before indexing new IDs.
+    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+        if (file.content === null)
+            addChange(changes, file.relativePath, null, operation.id, 'text/plain');
     // Start from empty derived files so no base-game position or supply line survives.
     for (const name of [
         'buildings.txt',
@@ -3309,7 +3339,28 @@ function applyCreateWorld(base, changes, operation) {
     const positioned = currentIndex(base, changes);
     for (const file of planSupplyRebuild(positioned, { mode: 'replace' }))
         addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
+    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+        addChange(changes, file.relativePath, file.content, operation.id, file.mediaType ?? 'text/plain');
     return [
+        ...(reference?.diagnostics ?? []).map((message) => ({
+            code: 'MAP_REFERENCE_INTERPRETATION',
+            severity: 'warning',
+            category: 'map',
+            operationId: operation.id,
+            message,
+        })),
+        ...(world.warnings.length === 0
+            ? []
+            : [
+                {
+                    code: 'MAP_WORLD_GENERATION_REVIEW',
+                    severity: 'warning',
+                    category: 'map',
+                    operationId: operation.id,
+                    message: `Drainage generation reported ${world.warnings.length} review notes`,
+                    details: { warningCount: world.warnings.length, samples: world.warnings.slice(0, 5) },
+                },
+            ]),
         {
             code: 'MAP_WORLD_CREATED',
             severity: 'info',
@@ -3405,7 +3456,7 @@ function applyEntityLocator(base, changes, operation) {
     ]);
     addChange(changes, locator.file.relativePath, output, operation.id, 'text/plain');
 }
-function* planMapOperationSteps(base, operations, signal) {
+function* planMapOperationSteps(base, operations, signal, context = {}) {
     yield* cancellationCheckpoint(signal);
     const changes = new Map();
     const diagnostics = [];
@@ -3443,7 +3494,7 @@ function* planMapOperationSteps(base, operations, signal) {
         const boundsCheckpoint = expectedChangedBounds;
         try {
             if (operation.kind === 'create_world')
-                diagnostics.push(...applyCreateWorld(base, changes, operation));
+                diagnostics.push(...applyCreateWorld(base, changes, operation, context));
             else if (operation.kind === 'move_state_provinces')
                 applyMoveStateProvinces(base, changes, operation);
             else if (operation.kind === 'update_state')
@@ -3522,12 +3573,12 @@ function* planMapOperationSteps(base, operations, signal) {
         operations: manifestOperations,
     };
 }
-export function planMapOperations(base, operations, signal) {
-    return completeSynchronously(planMapOperationSteps(base, operations, signal));
+export function planMapOperations(base, operations, signal, context = {}) {
+    return completeSynchronously(planMapOperationSteps(base, operations, signal, context));
 }
 /** Plans map mutations while periodically yielding so protocol cancellation can be delivered. */
-export async function planMapOperationsAsync(base, operations, signal) {
-    return completeCooperatively(planMapOperationSteps(base, operations, signal), signal);
+export async function planMapOperationsAsync(base, operations, signal, context = {}) {
+    return completeCooperatively(planMapOperationSteps(base, operations, signal, context), signal);
 }
 export function mapOperationId(operation) {
     return deterministicId('map_operation', operation);