Initial commit

docs/superpowers/specs/2026-04-01-combat-ui-unit-panel-design.md

@@ -0,0 +1,68 @@
+# Combat UI: Unit Info Panel
+
+## Overview
+
+Replace the current exit-button-only CombatUI with a unit info panel that displays the selected unit's name and HP. The panel appears in the bottom-left corner when a unit is selected and hides when deselected.
+
+## Scene Structure
+
+```
+CombatUI (CanvasLayer) — script: scripts/combat_ui.gd
+  └─ UnitPanel (PanelContainer) — anchored bottom-left, hidden by default
+       └─ MarginContainer
+            └─ VBoxContainer
+                 ├─ NameLabel (Label) — displays unit name
+                 └─ HPBar (ProgressBar) — displays current_hp / max_hp
+```
+
+- The existing exit button and its VBoxContainer are removed entirely.
+- The CombatUI CanvasLayer is preserved; its theme reference to `main_ui_theme.tres` stays.
+
+## Layout
+
+- UnitPanel is anchored to the bottom-left of the viewport.
+- Margin of 8px from the left and bottom edges.
+- Panel width: ~200px (enough for name and HP bar).
+- Height: determined by contents.
+
+## Behavior
+
+### Unit Discovery
+
+CombatUI finds units by looking for nodes in the `"units"` group. Units must be added to this group — this is done in `unit.tscn` (scene-level group assignment) or in `unit.gd`'s `_ready()`.
+
+### Signal Connection
+
+On `_ready()`, CombatUI:
+1. Calls `get_tree().get_nodes_in_group("units")` to find all current units.
+2. Connects each unit's `unit_selected_changed(unit: Unit, selected: bool)` signal to a handler.
+
+### Selection Handling
+
+When `unit_selected_changed` is received:
+- If `selected == true`: populate NameLabel with `unit.current_info.name`, set HPBar's `max_value` to `unit.current_stats.max_hp` and `value` to `unit.current_stats.current_hp`, show UnitPanel.
+- If `selected == false`: hide UnitPanel.
+
+### Edge Cases
+
+- If no units exist in the group at ready time, the panel simply stays hidden.
+- If a unit is removed from the scene (e.g., defeated), the signal disconnects naturally with the node. The panel hides if that unit was selected.
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `prefabs/combat_ui.tscn` | Remove exit button/VBoxContainer. Add UnitPanel with NameLabel and HPBar. Attach new script. |
+| `scripts/combat_ui.gd` | New script: connects to unit signals, shows/hides panel, populates data. |
+| `prefabs/unit.tscn` | Add the node to the `"units"` group. |
+
+## Styling
+
+Uses the existing `main_ui_theme.tres` applied at the CombatUI or UnitPanel level. No new theme resources needed.
+
+## Out of Scope
+
+- Full stat display (ATK, DEF, etc.) — future expansion.
+- Animations (fade/slide) — instant show/hide only.
+- Pause menu / exit button — separate future feature.
+- HP bar color theming — uses default ProgressBar style from theme.