hoi4-agent-tools 3.5.1 → 3.6.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 3.6.0 - 2026-09-27
+
+- Preview immediate tooltip text from source localisation with declared position, width and padding, using the source tooltip sprite and font.
+- Keep unknown GUI visibility and enablement separate from confirmed states, branch coverage and click regions.
+- Identify inferred scrollbar gutter geometry as approximate.
+- Provide a shorter setup guide, practical examples with real renders, and a separate tool reference; remove redundant planning and release-history documents.
+
 ## 3.5.1 - 2026-09-27
 
 - Preserve installed-game and offline-wiki citations in compact reference context bundles, select question-relevant sections within required sources, and report sources omitted by the result limit separately from missing files.

package/README.md

@@ -1,137 +1,64 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains, decisions, cross-system dependencies, technology systems, AI weights, and MTTH timing and to inspect, create, or clean up focus trees, scripted GUIs, and maps. It produces source-linked structural and visual evidence that agents can use inside a larger modding workflow.
+Give your coding agent tools for Hearts of Iron IV modding.
+Read mod files, find the right documentation, preview trees and interfaces, and make focused changes to focus trees, GUIs and maps.
 
-## What it does
+## Get started
 
-- Focus trees: inspect structure and references, render layouts, create trees, and reorganize existing branches.
-- Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render value-driven variants, dynamic country flags, inline text icons, states, resolutions, hierarchy, and click regions; diagnose alignment, visibility, clipping, panel containment, and button-label centering; create or repair interface source.
-- Maps: navigate the complete rendered map by ID or localised name; inspect provinces, states, regions, adjacency, supply, railways, and positions; create states and provinces; change IDs; and repair connected map data.
-- Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
-- Cross-system impact and decisions: trace definitions and consumers across source systems, evaluate declared actor and target scenarios, inspect costs and mission paths, and compare in-memory proposals.
-- Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
-- AI and MTTH: evaluate weighted choices and timing across explicit scenarios, bind special scope chains, enumerate dynamic target pools, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
-- Local references: search and read cited offline wiki pages, installed game documentation, optional script documentation, and exact source symbols without loading whole manuals into the conversation.
+Install [Node.js](https://nodejs.org/) 22.19+ in the Node 22 line, or Node.js 24, then run:
 
-## Real results
+```bash
+npm install --global hoi4-agent-tools
+hoi4-agent-tools-setup --print-client-config
+```
 
-The examples use real installed vanilla and Chaos Redux source, supplied game captures, and explicit reproducible display scenarios. They demonstrate source-backed review, not a claim of 99.9% whole-image accuracy. Images, source revisions, hashes, and known differences are in [Visual comparisons](docs/visual-comparisons.md) and [Interface examples](docs/gui-comparisons.md).
+Add the printed configuration to your MCP client and open your mod as its workspace.
+Keep an installed copy of HOI4 available for vanilla examples, artwork and fonts.
+The [setup guide](docs/setup.md) covers connecting your agent and choosing game or mod paths.
 
-| Options Video in game                                                          | Options Video from the MCP renderer                                                                |
-| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| ![Options Video in game](docs/images/comparisons/gui/options-video-ingame.png) | ![Options Video rendered from installed source](docs/images/comparisons/gui/options-video-mcp.png) |
+Then try:
 
-| Škoda Priority in game                                                           | Škoda Priority from the MCP renderer                                                                 |
-| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| ![Škoda Priority in game](docs/images/comparisons/gui/skoda-priority-ingame.png) | ![Škoda Priority rendered from installed source](docs/images/comparisons/gui/skoda-priority-mcp.png) |
+> Render this mod's focus trees and show which prerequisites are alternatives.
 
-The interface gallery also includes Chaos Redux Settings, Event Log, and Chaos Meter, plus populated vanilla decision and occupation templates. Their manifests separate source-defined layout from declared native runtime fields.
+> Find the installed documentation for `save_event_target_as`, read the relevant section, and show a vanilla example.
 
-The other workbenches return complete source-linked layouts and catalogs rather than prose-only summaries.
+> Preview this scripted GUI at 100% and 125% UI scale and check for clipped text or overlapping controls.
 
-For the supplied focus and technology game captures beside current-source MCP renders, see [Visual examples and comparison limits](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/visual-comparisons.md). These comparisons do not establish 99.9% whole-image accuracy.
+## What you can do
 
-| Fury focus tree from Chaos Redux                                                          | Infantry technology folder from Chaos Redux and vanilla                                                |
-| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| ![Fury focus tree rendered from Chaos Redux source](docs/images/comparisons/fury-mcp.png) | ![Infantry technology folder rendered from installed source](docs/images/comparisons/infantry-mcp.png) |
+| Task                                                                 | Guide                                                                    |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Find the right wiki section, game documentation or source definition | [Local references](docs/reference.md)                                    |
+| Inspect, preview, create or reorganize a focus tree                  | [Focus trees](docs/focus.md)                                             |
+| Trace event chains, decisions, costs and dependencies                | [Events](docs/events.md) · [Decisions](docs/analysis.md)                 |
+| Preview technology and doctrine trees                                | [Technology trees](docs/technology.md)                                   |
+| Inspect and repair scripted interfaces                               | [Scripted GUIs](docs/gui.md)                                             |
+| Find states and provinces, preview maps and edit connected map data  | [Maps](docs/map.md)                                                      |
+| Compare AI weights and test declared mechanic scenarios              | [AI analysis](docs/probability.md) · [Mechanic tests](docs/mechanics.md) |
 
-| Map                                                                              | Event options                                                                                      |
-| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| ![Installed map rendered by the MCP](docs/images/comparisons/source/map-mcp.png) | ![Chaos Redux event chain rendered by the MCP](docs/images/comparisons/source/event-chain-mcp.png) |
+## Real examples
 
-These two views retain native output resolution. Their [source manifest](docs/images/comparisons/source/manifest.json) records the map revision and the exact Fury event used for the option view. The event renderer's omitted-node count includes the rest of the workspace graph outside that selection.
+These previews were rendered from Chaos Redux and installed HOI4 files.
+Click an image to open it at full size.
 
-## Use from a coding agent
+| Fury focus tree                                                                                  | Vanilla Options interface                                                                                                    |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| [![Fury focus tree](docs/images/comparisons/fury-mcp.png)](docs/images/comparisons/fury-mcp.png) | [![Options interface](docs/images/comparisons/gui/options-video-mcp.png)](docs/images/comparisons/gui/options-video-mcp.png) |
 
-Requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
+Follow the [examples guide](docs/examples.md) for useful prompts and expected results.
+See [focus and technology comparisons](docs/visual-comparisons.md) and [interface comparisons](docs/gui-comparisons.md) for supplied in-game captures beside the renders.
 
-```bash
-npm install --global hoi4-agent-tools@latest
-```
+## How it fits your workflow
 
-```toml
-[mcp_servers.hoi4_agent_tools]
-command = "hoi4-agent-tools.cmd"
-startup_timeout_sec = 120
-tool_timeout_sec = 600
-```
+The server works through your coding agent and follows the mod workspace you provide.
+It keeps large renders and reports in linked files, and retrieves relevant documentation sections instead of whole manuals.
+Your repository instructions and review process still apply.
 
-On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repositories can include these steps in their agent template so the coding agent installs and registers the server itself; manual installation is not required in that workflow. Once connected, the server follows the active mod supplied by the client and the agent can call its HOI4 tools directly.
-
-## Tools
-
-| Tool                        | Purpose                                                                                   |
-| --------------------------- | ----------------------------------------------------------------------------------------- |
-| `hoi4.focus_inspect`        | Read focus trees, continuous-focus placement, and structural or reference problems.       |
-| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                         |
-| `hoi4.focus_raster`         | Produce a high-fidelity PNG review with decoded source icons.                             |
-| `hoi4.focus_rewrite`        | Create or update a focus tree.                                                            |
-| `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                      |
-| `hoi4.gui_render`           | Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics. |
-| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                    |
-| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.       |
-| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.    |
-| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.     |
-| `hoi4.reference_context`    | Get compact, cited wiki and installed documentation pointers for a modding surface.       |
-| `hoi4.reference_search`     | Search bounded local documentation sections.                                              |
-| `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                  |
-| `hoi4.source_lookup`        | Find exact definitions, overrides, usages, and narrow source blocks.                      |
-| `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                  |
-| `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.   |
-| `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                           |
-| `hoi4.impact_inspect`       | Trace symbol and changed-file consumers across source systems and compare proposals.      |
-| `hoi4.decision_inspect`     | Inventory and evaluate decisions or missions under declared scenarios and source changes. |
-| `hoi4.mechanic_test`        | Execute bounded source effects on a copied declared scenario and check assertions.        |
-| `hoi4.package_check`        | Check declarative package definitions, calls, registrations, assets, and case links.      |
-| `hoi4.scenario_test`        | Run named source and domain cases in resumable, revision-bound batches.                   |
-| `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                    |
-| `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                               |
-| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                   |
-| `hoi4.tech_render`          | Render source layouts with real item sizes and year guides, plus dependencies and assets. |
-| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.      |
-| `hoi4.probability_inspect`  | Locate weighted logic and discover compatible adapters, candidates, and required inputs.  |
-| `hoi4.probability_evaluate` | Evaluate exact values, probabilities, timing, bounds, and unresolved inputs.              |
-| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.         |
-| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                  |
-| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.          |
-| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                     |
-| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.         |
-
-Set `HOI4_AGENT_TOOLS_CHAOSX=1` on the server process to expose the optional `chaosx.focus_country_assets` and `chaosx.visual_revision` tools used by ChaosX workflows. They remain absent from the default public tool list.
-
-Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, follow the `continuationUri` returned in `_meta` until it is `null`; clients may also request byte ranges with `?offset=<bytes>&length=<bytes>`.
-
-Long-running domain calls advertise optional MCP task support. A task survives client disconnects and can be retrieved after reconnect; clients without task support keep the ordinary synchronous result contract. Native background rewrites require a stable caller-supplied `requestKey` so retries resolve to one durable mutation receipt. See [Persistent jobs and MCP tasks](docs/jobs.md).
-
-## Coexistence with agent workflows
-
-HOI4 Agent Tools provides HOI4 domain operations without replacing repository instructions such as `AGENTS.md`, skills, plans, or subagents. Its optional weighted-logic prompt helps an agent scope one probability analysis and then returns control to the normal workflow.
-
-Connecting and listing tools does not scan mod source. Compact tool schemas and linked resources keep large diagnostics, renders, and diffs out of the agent's working context until needed. Event, impact, decision, technology, and probability tools analyze source without editing it; only `hoi4.*_rewrite` calls edit mod source.
-
-## Create or clean content
-
-Ask your agent in normal task language. A typical workflow is inspect, render, rewrite, then inspect the result. The agent can call a raster tool when a pixel review is useful without paying that cost during every structural operation.
-
-- Focus trees: "Create a complete national focus tree for this route specification," or "Compact this existing tree into a balanced, readable layout." Existing trees can use a plan-free compact reflow; new trees use a complete plan. See [Focus trees](docs/focus.md).
-- Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render every value-driven version of this window and fix hidden controls, off-center button text, background alignment, clipping, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
-- Maps: "Render the whole map and find this state by name," "Create a state from these provinces," "Create a province inside this exact rectangle," or "Swap these state IDs and update connected references." See [Maps](docs/map.md).
-- Event chains: "Trace every route from this event and explain where its flags and variables change," or "Compare the workspace event graph with its previous revision and render the affected routes." See [Event chains](docs/events.md).
-- Cross-system impact and decisions: "Find every direct and transitive consumer of this idea," or "Compare who can take this decision, what they pay, and its mission end paths for these actor and target scenarios." See [Cross-system impact and decisions](docs/analysis.md).
-- Mechanics and packages: "Test this transfer's conservation and payment," or "Check every declared package link and resume its named scenario suite." See [Mechanic tests and scenario suites](docs/mechanics.md).
-- Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).
-- AI and MTTH: "Compare these focus weights across peace, defensive-war, and low-stability scenarios," or "Show when this MTTH event becomes likely and which unknown inputs control the result." See [AI and MTTH analysis](docs/probability.md).
-- References: "Find the installed effect signature and an exact vanilla example," or "Show the pertinent wiki and installed documentation for this GUI task." See [Local references](docs/reference.md).
-
-## HTTP
-
-Use stdio for local MCP clients. For shared or remote deployments, see [HTTP](docs/http.md).
-
-## Development
+Inspection and rendering do not edit the mod.
+The focus, GUI and map rewrite tools can change source files after checking the proposed edit.
+The server does not launch or control the game; previews and source tests cannot prove live clicks, AI choices or engine timing.
 
-```bash
-npm ci
-npm run check
-```
+[Documentation](docs/README.md) · [Tool reference](docs/tools.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
 
-See [Development](docs/development.md). Apache-2.0 licensed. Hearts of Iron IV and Paradox Interactive are trademarks of their respective owners; this project is unaffiliated.
+Apache-2.0 licensed.
+Hearts of Iron IV artwork belongs to its respective owners; this project is unaffiliated with Paradox Interactive.

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),