hoi4-agent-tools 3.5.1 → 3.7.0

package/dist/hoi4_agent_tools/gui/layout.js

@@ -5,7 +5,7 @@ import { ServiceError } from '../core/result.js';
 import { GuiAssetCatalog } from './assets.js';
 import { GUI_GRAPH_MAX_EDGES, GUI_GRAPH_MAX_ELEMENTS, GUI_GRAPH_MAX_NODES, GUI_SCENE_MAX_DEPTH, GUI_SCENE_MAX_ELEMENTS, GUI_SCENE_MAX_TEXT_CHARACTERS, GUI_SCENE_MAX_TEXT_LAYOUT_OPERATIONS, GUI_SCENE_MAX_WORK, GUI_TEXT_MAX_CHARACTERS, GUI_TEXT_MAX_MISSING_GLYPH_SAMPLES, } from './limits.js';
 import { guiElementAttributeFidelity } from './source-graph.js';
-import { emptyFidelityReport } from './types.js';
+import { emptyFidelityReport, fidelityCategories } from './types.js';
 import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
 import { evaluateGuiCondition, guiConditionScenario } from './scenario-conditions.js';
 import { parseClausewitz } from '../core/source/index.js';
@@ -636,13 +636,29 @@ function refreshSceneClips(context) {
             : geometry.appearanceVisible
                 ? 'outside_clip'
                 : (element.visibilityReason ?? 'visibility_false');
+        element.visibilityStatus =
+            intersection === undefined
+                ? 'hidden'
+                : element.visibilityStatusReason !== undefined
+                    ? 'unresolved'
+                    : element.visible
+                        ? 'shown'
+                        : 'hidden';
         if (clickableTypes.test(element.elementType)) {
             const reason = element.visible ? geometry.interactionBlock : 'hidden';
             if (reason === undefined)
                 delete element.disabledReason;
             else
                 element.disabledReason = reason;
-            element.clickable = reason === undefined;
+            element.enablement =
+                geometry.interactionBlock !== undefined
+                    ? 'disabled'
+                    : element.visibilityStatus === 'unresolved' || element.enablementReason !== undefined
+                        ? 'unresolved'
+                        : reason === undefined
+                            ? 'enabled'
+                            : 'disabled';
+            element.clickable = element.enablement === 'enabled';
         }
     }
 }
@@ -1142,7 +1158,7 @@ async function layoutAttachedScrollbars(definition, scrollbars, owner, childOutp
             vertical.rect.y = Math.max(verticalRect.y, horizontalRect.y + horizontalRect.height);
             vertical.rect.height = Math.max(0, verticalRect.y + verticalRect.height - vertical.rect.y);
         }
-        addFidelity(context.fidelity, 'modelled', 'orthogonal_scrollbar_gutters', 'Visible horizontal and vertical scrollbars reserve their anchored cross-axis gutters instead of drawing their end buttons over the same corner.', definition);
+        addFidelity(context.fidelity, 'approximated', 'orthogonal_scrollbar_gutters', 'Visible horizontal and vertical scrollbars reserve their anchored cross-axis gutters instead of drawing their end buttons over the same corner.', definition);
     }
     for (const bar of barLayouts) {
         await layoutElement({
@@ -1232,6 +1248,11 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     if (height < 0)
         height = Math.max(0, parentRect.height - localY + height);
     const explicitlyVisible = explicitElementVisibility(definition, scenario, rowValues);
+    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 declaredHidden = scalarBoolean(property(definition.attributes, 'hide', 'hidden')) ?? false;
     const sourceVisible = scalarBoolean(property(definition.attributes, 'visible')) ?? !declaredHidden;
     const resolveVisibleAppearance = inheritedVisible && (explicitlyVisible ?? sourceVisible);
@@ -1240,6 +1261,11 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
         scenario.scriptedGui[`${definition.name}.enabled`] ??
         context.constantElementEnabled[definition.name] ??
         scalarBoolean(property(definition.attributes, 'enabled'));
+    const unresolvedEnabledReason = context.unresolvedElementEnabled.get(definition.name);
+    const explicitEnabled = rowValues?.[`${definition.name}.enabled`] ??
+        scenario.values[`${definition.name}.enabled`] ??
+        scenario.scriptedGui[`${definition.name}.enabled`];
+    const enablementUnresolved = unresolvedEnabledReason !== undefined && typeof explicitEnabled !== 'boolean';
     const requestedState = scenario.elementStates[definition.name] ?? scenario.state;
     const state = scriptedEnabled === false ? 'disabled' : requestedState;
     const backgroundValue = property(definition.attributes, 'background');
@@ -1595,6 +1621,12 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const clipped = clipRect !== undefined &&
         (availableClip === undefined || !equalRect(unclippedRect, availableClip));
     const visible = resolveVisibleAppearance && (availableClip !== undefined || inheritedClip === undefined);
+    const visibilityStatusReason = explicitlyVisible === false
+        ? undefined
+        : (parentUnresolvedVisibility ??
+            (inheritedVisible && explicitlyVisible === undefined
+                ? unresolvedVisibilityReason
+                : undefined));
     const clickThrough = scalarBoolean(property(definition.attributes, 'clickThrough', 'alwaystransparent', 'allwaystransparent')) ?? false;
     const interactive = clickableTypes.test(definition.elementType);
     const interactionBlock = !interactive
@@ -1607,7 +1639,21 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
                     ? 'scenario_state'
                     : undefined;
     const disabledReason = interactive && !visible ? 'hidden' : interactionBlock;
-    const clickable = interactive && disabledReason === undefined;
+    const visibilityStatus = availableClip === undefined && inheritedClip !== undefined
+        ? 'hidden'
+        : visibilityStatusReason !== undefined
+            ? 'unresolved'
+            : visible
+                ? 'shown'
+                : 'hidden';
+    const enablement = interactionBlock !== undefined
+        ? 'disabled'
+        : visibilityStatus === 'unresolved' || enablementUnresolved
+            ? 'unresolved'
+            : disabledReason === undefined
+                ? 'enabled'
+                : 'disabled';
+    const clickable = interactive && enablement === 'enabled';
     const visibilityReason = visible
         ? 'visible'
         : !inheritedVisible
@@ -1661,7 +1707,11 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
         zIndex: context.output.length,
         visible,
         visibilityReason,
+        visibilityStatus,
+        ...(visibilityStatusReason === undefined ? {} : { visibilityStatusReason }),
         clickable,
+        ...(interactive ? { enablement } : {}),
+        ...(interactive && enablementUnresolved ? { enablementReason: unresolvedEnabledReason } : {}),
         ...(disabledReason === undefined ? {} : { disabledReason }),
         clickThrough,
         rect: availableClip ?? { x: unclippedRect.x, y: unclippedRect.y, width: 0, height: 0 },
@@ -1977,6 +2027,8 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     const scriptedWindowVisibility = {};
     const constantElementVisibility = {};
     const constantElementEnabled = {};
+    const unresolvedElementEnabled = new Map();
+    const unresolvedElementVisibility = new Map();
     const resolvedScriptedProperties = {};
     const dynamicListsByName = new Map();
     const countryFlagProperties = new Map();
@@ -2033,11 +2085,25 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
                     ...scenario.variables,
                     ...scenario.values,
                 });
-                if (resolved === undefined)
-                    continue;
                 const key = `${propertyDefinition.elementName}.${suffix}`;
-                if (scenario.values[key] === undefined)
-                    resolvedScriptedProperties[key] = resolved;
+                if (suffix === 'visible' || suffix === 'enabled') {
+                    const booleanValue = scalarBoolean(resolved ?? expression);
+                    if (booleanValue === undefined) {
+                        const reason = `${scripted.name}.${key}: scenario has no boolean value for ${typeof expression === 'string' ? expression : JSON.stringify(expression)}.`;
+                        (suffix === 'visible' ? unresolvedElementVisibility : unresolvedElementEnabled).set(propertyDefinition.elementName, reason);
+                        addFidelity(fidelity, 'unresolved', 'scripted_gui_scenario_property', reason);
+                        continue;
+                    }
+                    (suffix === 'visible' ? unresolvedElementVisibility : unresolvedElementEnabled).delete(propertyDefinition.elementName);
+                    if (scenario.values[key] === undefined)
+                        resolvedScriptedProperties[key] = booleanValue;
+                }
+                else {
+                    if (resolved === undefined)
+                        continue;
+                    if (scenario.values[key] === undefined)
+                        resolvedScriptedProperties[key] = resolved;
+                }
                 addFidelity(fidelity, 'modelled', 'scripted_gui_scenario_property', `${key} resolved from a scenario runtime value.`);
             }
         }
@@ -2051,13 +2117,23 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
                     ? undefined
                     : evaluated.state === 'true';
             if (result === undefined) {
-                addFidelity(fidelity, 'unresolved', 'scripted_gui_trigger', `${trigger.name} requires more scenario facts.`);
+                if (trigger.name.endsWith('_visible'))
+                    unresolvedElementVisibility.set(trigger.elementName, `${scripted.name}.${trigger.name}: ${evaluated?.unresolved.map(({ message }) => message).join('; ') ?? 'condition requires more scenario facts'}`);
+                if (trigger.name.endsWith('_click_enabled'))
+                    unresolvedElementEnabled.set(trigger.elementName, `${scripted.name}.${trigger.name}: ${evaluated?.unresolved.map(({ message }) => message).join('; ') ?? 'condition requires more scenario facts'}`);
+                addFidelity(fidelity, 'unresolved', 'scripted_gui_trigger', unresolvedElementVisibility.get(trigger.elementName) ??
+                    unresolvedElementEnabled.get(trigger.elementName) ??
+                    `${scripted.name}.${trigger.name} requires more scenario facts.`);
                 continue;
             }
             if (trigger.name.endsWith('_visible'))
                 constantElementVisibility[trigger.elementName] = result;
+            if (trigger.name.endsWith('_visible'))
+                unresolvedElementVisibility.delete(trigger.elementName);
             if (trigger.name.endsWith('_click_enabled'))
                 constantElementEnabled[trigger.elementName] = result;
+            if (trigger.name.endsWith('_click_enabled'))
+                unresolvedElementEnabled.delete(trigger.elementName);
             addFidelity(fidelity, 'modelled', trigger.constantResult === undefined
                 ? 'scripted_gui_trigger'
                 : 'scripted_gui_constant_trigger', `${trigger.name} resolves to ${result ? 'yes' : 'no'}.`);
@@ -2117,6 +2193,8 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
         dynamicListsByName,
         countryFlagProperties,
         constantElementEnabled,
+        unresolvedElementEnabled,
+        unresolvedElementVisibility,
         spritesByName: new Map(graph.sprites.map((sprite) => [sprite.name.toLowerCase(), sprite])),
         localisation,
         output,
@@ -2171,11 +2249,158 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
         });
     }
     refreshSceneClips(context);
+    let tooltipPreview;
+    if (scenario.tooltip !== undefined) {
+        const { target: targetToken, x, y, width, padding } = scenario.tooltip;
+        const textWidth = width - 2 * padding;
+        const skipTooltip = (code, message) => {
+            diagnostics.push({ code, severity: 'warning', category: 'rendering', message });
+            addFidelity(fidelity, 'unresolved', 'immediate_tooltip_preview', message);
+        };
+        const matches = output.filter(({ id, name }) => id === targetToken || name === targetToken);
+        const target = matches[0];
+        if (matches.length === 0)
+            skipTooltip('GUI_TOOLTIP_TARGET_MISSING', `Tooltip target ${targetToken} is absent from the scene.`);
+        else if (matches.length > 1)
+            skipTooltip('GUI_TOOLTIP_TARGET_AMBIGUOUS', `Tooltip target ${targetToken} matches ${matches.length} scene elements; select an instance id.`);
+        else if (target?.visibilityStatus === 'unresolved')
+            skipTooltip('GUI_TOOLTIP_TARGET_UNRESOLVED', `Tooltip target ${targetToken} has unresolved visibility: ${target.visibilityStatusReason ?? 'more scenario facts are required'}.`);
+        else if (target?.visible !== true)
+            skipTooltip('GUI_TOOLTIP_TARGET_HIDDEN', `Tooltip target ${targetToken} is hidden in this preview.`);
+        else {
+            const source = elementsById.get(target.sourceId);
+            const localisationKey = source === undefined ? undefined : scalarString(property(source.attributes, 'pdx_tooltip'));
+            const localised = localisationKey === undefined
+                ? undefined
+                : (scenario.localisation[localisationKey] ?? localisation.get(localisationKey));
+            const tooltipSprite = graph.sprites.find(({ name }) => name.toLowerCase() === 'tooltip');
+            const tooltipFont = catalog.fontDefinition('cg_16b');
+            if (localisationKey === undefined)
+                skipTooltip('GUI_TOOLTIP_KEY_MISSING', `Tooltip target ${targetToken} has no pdx_tooltip localisation key.`);
+            else if (localised === undefined)
+                skipTooltip('GUI_TOOLTIP_LOCALISATION_MISSING', `Tooltip localisation ${localisationKey} is unavailable in ${scenario.language}.`);
+            else if (tooltipSprite === undefined)
+                skipTooltip('GUI_TOOLTIP_SPRITE_MISSING', 'The declared ToolTip text sprite is unavailable.');
+            else if (tooltipFont === undefined ||
+                catalog.resolvedFontMetrics('cg_16b').source === 'approximation')
+                skipTooltip('GUI_TOOLTIP_FONT_MISSING', 'The declared cg_16b tooltip font or its metrics are unavailable.');
+            else if (x + width > scenario.resolution.width || y >= scenario.resolution.height)
+                skipTooltip('GUI_TOOLTIP_BOUNDS', 'Caller-declared tooltip position and width exceed the viewport.');
+            else {
+                const spriteFrame = await catalog.loadSpriteFrame(tooltipSprite, 0);
+                if (spriteFrame?.supported !== true || spriteFrame.dataUri === undefined)
+                    skipTooltip('GUI_TOOLTIP_SPRITE_MISSING', spriteFrame?.reason ?? 'The ToolTip texture is unavailable.');
+                else {
+                    const missingEngineText = [];
+                    const suppliedText = replaceTextBounded(localised, /\[![^\]]+\]/gu, (match) => {
+                        const token = match[0];
+                        const supplied = scenario.values[token] ?? scenario.scriptedGui[token];
+                        if (typeof supplied === 'string' && supplied.length > 0)
+                            return supplied;
+                        missingEngineText.push(token);
+                        return token;
+                    }, 'GUI tooltip supplied effect text');
+                    const resolved = resolveTokenText(suppliedText, scenario, localisation);
+                    const unresolved = [
+                        ...new Set([
+                            ...missingEngineText,
+                            ...resolved.unresolved,
+                            ...[...resolved.text.matchAll(/\[![^\]]+\]/gu)].map(([token]) => token),
+                        ]),
+                    ];
+                    if (unresolved.length > 0)
+                        skipTooltip('GUI_TOOLTIP_TEXT_UNRESOLVED', `Tooltip ${localisationKey} requires supplied values for ${unresolved.join(', ')}.`);
+                    else {
+                        const tooltipTextDefinition = {
+                            id: `tooltip-preview:${target.id}:text`,
+                            name: `${target.name}_immediate_tooltip_text`,
+                            elementType: 'instantTextBoxType',
+                            sourcePath: source?.sourcePath ?? target.sourcePath,
+                            childIds: [],
+                            attributes: {
+                                position: { x: (x + padding) / baseScale, y: (y + padding) / baseScale },
+                                size: { width: textWidth / baseScale, height: 0 },
+                                text: suppliedText,
+                                font: 'cg_16b',
+                                multiline: true,
+                                fixedsize: true,
+                            },
+                            unsupportedAttributes: [],
+                            rawSource: '',
+                            definitionOrder: source?.definitionOrder ?? 0,
+                        };
+                        const tooltipContext = {
+                            ...context,
+                            output: [],
+                            instancesById: new Map(),
+                            geometry: new Map(),
+                            fidelity: emptyFidelityReport(),
+                            diagnostics: [],
+                            work: new GuiSceneWorkBudget(),
+                        };
+                        await layoutElement(tooltipTextDefinition, viewport, viewport, baseScale, 0, tooltipContext);
+                        refreshSceneClips(tooltipContext);
+                        const textElement = tooltipContext.output[0];
+                        const popupText = textElement?.text;
+                        if (textElement === undefined ||
+                            popupText === undefined ||
+                            popupText.unresolvedTokens.length > 0 ||
+                            popupText.metricSource === 'approximation' ||
+                            popupText.glyphLines.some(({ source: glyphSource, missingGlyphs }) => glyphSource === 'deterministic-fallback' || missingGlyphs.length > 0) ||
+                            popupText.inlineIcons?.some(({ sprite }) => sprite?.supported !== true || sprite.dataUri === undefined))
+                            skipTooltip('GUI_TOOLTIP_ASSET_OR_TEXT_UNRESOLVED', `Tooltip ${localisationKey} has unresolved text, glyph, icon, or texture data.`);
+                        else if (popupText.overflowX ||
+                            popupText.overflowY ||
+                            y + popupText.measuredHeight + 2 * padding > scenario.resolution.height)
+                            skipTooltip('GUI_TOOLTIP_BOUNDS', 'Tooltip text does not fit the caller-declared inset or the padded layout exceeds the viewport.');
+                        else {
+                            const backgroundDefinition = {
+                                ...tooltipTextDefinition,
+                                id: `tooltip-preview:${target.id}`,
+                                name: `${target.name}_immediate_tooltip`,
+                                elementType: 'iconType',
+                                attributes: {
+                                    position: { x: x / baseScale, y: y / baseScale },
+                                    size: {
+                                        width: width / baseScale,
+                                        height: (popupText.measuredHeight + 2 * padding) / baseScale,
+                                    },
+                                    spriteType: tooltipSprite.name,
+                                },
+                            };
+                            await layoutElement(backgroundDefinition, viewport, viewport, baseScale, 0, tooltipContext);
+                            const backgroundElement = tooltipContext.instancesById.get(backgroundDefinition.id);
+                            backgroundElement.zIndex = 0;
+                            textElement.zIndex = 1;
+                            textElement.depth = 1;
+                            textElement.parentId = backgroundElement.id;
+                            tooltipPreview = {
+                                targetId: target.id,
+                                localisationKey,
+                                placement: 'caller-declared',
+                                element: backgroundElement,
+                                textElement,
+                            };
+                            for (const category of fidelityCategories)
+                                fidelity[category].push(...tooltipContext.fidelity[category]);
+                            fidelity.ignored = fidelity.ignored.filter(({ field, elementId }) => field !== 'pdx_tooltip' || elementId !== target.sourceId);
+                            addFidelity(fidelity, 'approximated', 'immediate_tooltip_preview', `Immediate tooltip ${localisationKey} uses caller-declared viewport position, width, and ${padding}px padding with ToolTip and cg_16b; native placement, padding, and timing remain unverified.`);
+                            addFidelity(fidelity, 'approximated', 'tooltip_text_sprite_composition', 'ToolTip textSpriteType texture is stretched to the measured text height plus caller-declared padding; native frame composition is unverified.');
+                            addFidelity(fidelity, 'unsupported', 'pdx_tooltip_delayed', 'Delayed tooltip timing is not previewed.');
+                            addFidelity(fidelity, 'unsupported', 'click_to_front', 'Tooltip preview does not model click_to_front behavior.');
+                        }
+                    }
+                }
+            }
+        }
+    }
     output.sort((left, right) => left.zIndex - right.zIndex || compareCodeUnits(left.id, right.id));
-    const bounds = unionRects(output.flatMap((element) => {
+    const bounds = unionRects([...output, ...(tooltipPreview === undefined ? [] : [tooltipPreview.element])].flatMap((element) => {
         if (!element.visible)
             return [];
-        const painted = element.sprite === undefined && element.progressColours === undefined ? [] : [element.rect];
+        const painted = element.sprite === undefined && element.progressColours === undefined
+            ? []
+            : [element.rect];
         const text = element.text;
         if (text !== undefined && text.text.length > 0) {
             const rect = element.unclippedRect;
@@ -2209,6 +2434,7 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
         scenario,
         resolution: scenario.resolution,
         elements: output,
+        ...(tooltipPreview === undefined ? {} : { tooltipPreview }),
         bounds,
         fidelity,
         diagnostics: sortDiagnostics(diagnostics),

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -39,7 +39,10 @@ function bitmapDefinitionId(key, layer = 'face') {
 function sceneGlyphDefinitions(scene) {
     const outlines = new Map();
     const bitmaps = new Map();
-    for (const element of scene.elements) {
+    for (const element of [
+        ...scene.elements,
+        ...(scene.tooltipPreview === undefined ? [] : [scene.tooltipPreview.textElement]),
+    ]) {
         for (const line of element.text?.glyphLines ?? []) {
             for (const glyph of line.glyphs) {
                 if (glyph.kind === 'outline')
@@ -400,6 +403,8 @@ function renderOverlay(element, variant, toolText) {
     if (rect.width <= 0 || rect.height <= 0)
         return '';
     if (variant === 'click-regions') {
+        if (element.enablement === 'unresolved')
+            return `<g><rect ${rectAttributes(rect)} fill="#ffb84d" fill-opacity="0.12" stroke="#ffb84d" stroke-width="2" stroke-dasharray="5 3"/><title>${escapeXml(`Potential click region: ${element.enablementReason ?? element.visibilityStatusReason ?? element.name}`)}</title>${toolText.render(`${element.name} (?)`, { x: rect.x + 3, y: rect.y + 13, fontSize: 11, fill: '#ffb84d' })}</g>`;
         if (!element.clickable)
             return '';
         return `<g><rect ${rectAttributes(rect)} fill="#00d4ff" fill-opacity="0.2" stroke="#00d4ff" stroke-width="2"/>${toolText.render(element.name, { x: rect.x + 3, y: rect.y + 13, fontSize: 11, fill: '#00d4ff' })}</g>`;
@@ -418,6 +423,13 @@ function renderOverlay(element, variant, toolText) {
     }
     return '';
 }
+function renderTooltipPreview(scene, toolText) {
+    const tooltip = scene.tooltipPreview;
+    if (tooltip === undefined)
+        return '';
+    return (renderBaseElement(tooltip.element, undefined, toolText) +
+        renderBaseElement(tooltip.textElement, undefined, toolText));
+}
 function viewFor(scene, variant) {
     if (variant !== 'cropped' || scene.bounds.width <= 0 || scene.bounds.height <= 0) {
         return {
@@ -453,7 +465,7 @@ export function sceneToSvg(scene, variant) {
         : [`<clipPath id="clip-${index}"><rect ${rectAttributes(element.clipRect)}/></clipPath>`]);
     const body = scene.elements
         .map((element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText))
-        .join('');
+        .join('') + renderTooltipPreview(scene, toolText);
     const overlays = scene.elements
         .map((element) => renderOverlay(element, variant, toolText))
         .join('');
@@ -479,7 +491,7 @@ async function sceneToSvgCooperative(scene, variant, signal) {
     const clipDefinitions = await cooperativeParts(scene.elements, (element, index) => element.clipRect === undefined
         ? ''
         : `<clipPath id="clip-${index}"><rect ${rectAttributes(element.clipRect)}/></clipPath>`, signal);
-    const body = await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal);
+    const body = (await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal)) + renderTooltipPreview(scene, toolText);
     const overlays = await cooperativeParts(scene.elements, (element) => renderOverlay(element, variant, toolText), signal);
     const fidelity = escapeXml(canonicalJson(scene.fidelity));
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs><rect ${rectAttributes(view.viewBox)} fill="#17202a"/>${body}${overlays}</svg>`;
@@ -526,6 +538,27 @@ export function hierarchyToSvg(scene) {
 function sceneLayoutEvidence(scene) {
     return {
         ...scene,
+        ...(scene.tooltipPreview === undefined
+            ? {}
+            : {
+                tooltipPreview: {
+                    targetId: scene.tooltipPreview.targetId,
+                    localisationKey: scene.tooltipPreview.localisationKey,
+                    placement: scene.tooltipPreview.placement,
+                    element: {
+                        id: scene.tooltipPreview.element.id,
+                        rect: scene.tooltipPreview.element.rect,
+                        sprite: scene.tooltipPreview.element.sprite?.spriteName,
+                    },
+                    textElement: {
+                        id: scene.tooltipPreview.textElement.id,
+                        rect: scene.tooltipPreview.textElement.rect,
+                        text: scene.tooltipPreview.textElement.text?.text,
+                        lines: scene.tooltipPreview.textElement.text?.lines,
+                        fontName: scene.tooltipPreview.textElement.text?.fontName,
+                    },
+                },
+            }),
         elements: scene.elements.map((element) => ({
             ...element,
             ...(element.sprite === undefined

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -103,6 +103,24 @@ const GuiPreviewScenarioBodySchema = z
         .min(1)
         .max(128)
         .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
+    tooltip: z
+        .object({
+        target: elementNameSchema,
+        x: z.number().nonnegative(),
+        y: z.number().nonnegative(),
+        width: z.number().positive().max(RENDER_MAX_DIMENSION),
+        padding: z
+            .number()
+            .nonnegative()
+            .max(RENDER_MAX_DIMENSION / 2)
+            .describe('Caller-declared inset on each side, in viewport pixels; no native padding is inferred.'),
+    })
+        .strict()
+        .refine(({ padding, width }) => padding * 2 < width, {
+        path: ['padding'],
+        message: 'Tooltip padding must leave a positive text width.',
+    })
+        .optional(),
     description: z.string().max(500).optional(),
     date: GuiScenarioDateSchema.optional(),
     controls: ConditionControlMapSchema.optional(),