ux: add build cost and effect preview

[itsmiso-ai]

Fixes #138

Summary

• add reusable build effect copy beside existing build costs
• show a compact build preview in the dock with cost, missing resources, lock state, and effect
• surface selected build cost/effect while placement mode is active

Validation

• /data/git/windowstead/.tools/Godot_v4.2.2-stable_linux.x86_64 --headless --path /data/git/windowstead-138 --script res://tests/test_constants.gd
• /data/git/windowstead/.tools/Godot_v4.2.2-stable_linux.x86_64 --headless --path /data/git/windowstead-138 --script res://tests/test_runner.gd
• /data/git/windowstead/.tools/Godot_v4.2.2-stable_linux.x86_64 --headless --path /data/git/windowstead-138 --script res://tests/test_e2e.gd

[its-miso]

✅ Automated recommendation: APPROVE

Analysis engine: MiniMax-M2.7@https://litellm.jory.dev/v1 (anthropic)

PR #157 Review: "ux: add build cost and effect preview"

Recommendation: Approve

This PR fully addresses issue #138 by implementing a compact build cost and effect preview that surfaces during build selection and placement mode.

Changes Overview

File	Change	Summary
scenes/main.tscn	+6	Added BuildPreviewLabel node above build buttons
scripts/constants.gd	+6	Added BUILD_EFFECTS dictionary with descriptions for hut/workshop/garden
scripts/main.gd	+55/-7	Wired preview updates on hover/focus, added preview text generation functions
tests/test_constants.gd	+60/-33	Added tests for BUILD_EFFECTS data and consistency with BUILD_COSTS

Change-by-Change Findings

1. BUILD_EFFECTS constant (constants.gd)

• Adds descriptive game effects for each build type: housing support, build speed/unlock, food supply
• Correctly mirrors the key structure of BUILD_COSTS (hut/workshop/garden)
• Supports "clearer economy/build bottleneck feedback" open work theme

2. build_preview_text() and helpers (main.gd)

• Generates formatted preview: {name} • cost {costs} • {missing/available} • {effect} • {locked?}
• missing_build_resources() compares costs against current state.resources to compute shortage
• build_cost_text() formats resource costs with "free" fallback for empty costs
• Preview text used in: status label during placement, BuildPreviewLabel during selection/hover, button tooltips

3. Event wiring (main.gd)

• mouse_entered and focus_entered on build buttons trigger update_build_preview()
• open_build_popup() calls update_build_preview() to initialize on panel open
• Captures kind in closure to avoid stale reference in loop

4. Placement mode updates (main.gd)

• world_label.text extended to show placing {kind} • {costs}
• status_label.text set to full build_preview_text(kind) during placement

5. Test improvements (test_constants.gd)

• Fixed potential bug: fail_count = 28 - pass_count was hardcoded; now uses test_count - pass_count
• Added 4 tests for BUILD_EFFECTS content and 1 consistency test ensuring all costs have corresponding effects

Standards Compliance

Check	Status	Evidence
Follows AGENTS.md product direction	✓	Preview is compact, docked, surfaces before commitment
Build preview shown before committing	✓	begin_build_placement() shows preview before placement cursor
Missing resources indicated	✓	missing_build_resources() computes shortage, shows "available" or "missing X wood, Y stone"
Short game effect described	✓	BUILD_EFFECTS provides one-line descriptions aligned with issue examples
Works in compact dock UI	✓	Label placed above buttons, auto-wrap enabled
Reusable model with tests	✓	BUILD_EFFECTS is a constant dictionary, fully tested in test_constants.gd
Naming conventions	✓	Functions use snake_case, constants use SCREAMING_SNAKE_CASE
Typing consistency	✓	Parameters typed as String, return types declared, is_instance_valid() guard present
No breaking changes	✓	Only additions, no existing APIs modified

Linked Issue Fit: #138

All acceptance criteria are satisfied:

Criteria	Implementation
Build placement/selection shows cost before committing	world_label shows costs during placement; BuildPreviewLabel shows costs during selection
Missing resources clearly indicated	missing_text computed from missing_build_resources(), formatted as "missing N wood, M stone" or "available"
Building effects described in one short line	BUILD_EFFECTS provides short descriptions matching issue examples
Preview works in compact dock UI	BuildPreviewLabel positioned above buttons with autowrap_mode = 3
Tests for cost/effect data in reusable model	BUILD_EFFECTS as constant + 5 new tests in test_constants.gd

Tool Harness Findings

No tool requests were executed. The PR diff is complete and reviewable without external fetches. No security-sensitive operations detected.

Evidence Provider Findings

No evidence providers configured for this review.

Unknowns / Needs Verification

None. The PR has:

• Complete diff for all 4 files
• Clear connection to linked issue ux: add build cost and effect preview #138
• Validation commands included in PR body (all three test suites)
• Tests added for new data model