aether-shards/.agent/rules/ui/CombatHUD/RULE.md

---
description: Combat HUD UI component - tactical interface overlay during combat phase
globs: src/ui/components/CombatHUD.js, src/ui/components/CombatHUD.ts, src/types/CombatHUD.ts
alwaysApply: false
---

# **Combat HUD Rule**

The Combat HUD is the UI overlay active during the `GAME_RUN` / `ACTIVE` phase. It communicates turn order, unit status, and available actions to the player.

## **1. Visual Description**

**Layout:** A "Letterbox" style overlay that leaves the center of the screen clear for the 3D action.

### **A. Top Bar (Turn & Status)**

- **Turn Queue (Center-Left):** A horizontal list of circular portraits
  - _Active Unit:_ Larger, highlighted with a gold border on the far left
  - _Next Units:_ Smaller icons trailing to the right
  - _Enemy Intent:_ If an enemy is active, a small icon (Sword/Shield) indicates their planned action type
- **Global Info (Top-Right):**
  - _Round Counter:_ "Round 3"
  - _Threat Level:_ "High" (Color coded)

### **B. Bottom Bar (The Dashboard)**

- **Unit Status (Bottom-Left):**
  - _Portrait:_ Large 2D art of the active unit
  - _Bars:_ Health (Red), Action Points (Yellow), Charge (Blue)
  - _Buffs:_ Small icons row above the bars
- **Action Bar (Bottom-Center):**
  - A row of interactive buttons for Skills and Items
  - _Hotkeys:_ (1-5) displayed on the buttons
  - _State:_ Buttons go grey if AP is insufficient or Cooldown is active
  - _Tooltip:_ Hovering shows damage, range, and AP cost
- **End Turn (Bottom-Right):**
  - A prominent button to manually end the turn early (saving AP or Charge)

### **C. Floating Elements (World Space)**

- **Damage Numbers:** Pop up over units when hit
- **Health Bars:** Small bars hovering over every unit in the 3D scene (billboarded)

## **2. TypeScript Interfaces (Data Model)**

```typescript
// src/types/CombatHUD.ts

export interface CombatState {
    /** The unit currently taking their turn */
    activeUnit: UnitStatus | null;
    
    /** Sorted list of units acting next */
    turnQueue: QueueEntry[];
    
    /** Is the player currently targeting a skill? */
    targetingMode: boolean;
    
    /** Global combat info */
    roundNumber: number;
}

export interface UnitStatus {
    id: string;
    name: string;
    portrait: string;
    hp: { current: number; max: number };
    ap: { current: number; max: number };
    charge: number; // 0-100
    statuses: StatusIcon[];
    skills: SkillButton[];
}

export interface QueueEntry {
    unitId: string;
    portrait: string;
    team: 'PLAYER' | 'ENEMY';
    /** 0-100 progress to next turn */
    initiative: number; 
}

export interface StatusIcon {
    id: string;
    icon: string; // URL or Emoji
    turnsRemaining: number;
    description: string;
}

export interface SkillButton {
    id: string;
    name: string;
    icon: string;
    costAP: number;
    cooldown: number; // 0 = Ready
    isAvailable: boolean; // True if affordable and ready
}

export interface CombatEvents {
    'skill-click': { skillId: string };
    'end-turn': void;
    'hover-skill': { skillId: string }; // For showing range grid
}
```

## **3. Conditions of Acceptance (CoA)**

**CoA 1: Real-Time Updates**

- The HUD must update immediately when turn changes (via event listener)
- Health bars must reflect current HP after damage is dealt
- AP display must decrease when skills are used

**CoA 2: Skill Availability**

- Skills with insufficient AP must be visually disabled (greyed out)
- Skills on cooldown must show remaining turns
- Hovering a skill must highlight valid targets on the grid

**CoA 3: Turn Queue Accuracy**

- The queue must match the TurnSystem's predicted queue
- Enemy units in queue must show their team indicator

**CoA 4: Event Communication**

- Clicking a skill button must dispatch `skill-click` event
- Clicking "End Turn" must dispatch `end-turn` event
- The HUD must not directly call GameLoop methods (event-driven only)

## **4. Implementation Requirements**

Create `src/ui/components/CombatHUD.js` as a LitElement:

1. **Layout:** Use CSS Grid/Flexbox for letterbox layout (top bar, bottom bar, clear center)
2. **Data Binding:** Subscribe to TurnSystem events (`turn-start`, `turn-end`) and GameLoop combat state
3. **Turn Queue:** Render circular portraits in a horizontal row, highlighting the active unit
4. **Action Bar:** Map unit's skills to buttons, showing AP cost and cooldown state
5. **Event Handling:** Dispatch custom events for skill clicks and end turn actions
6. **Responsive:** Support mobile (vertical stack) and desktop (horizontal layout)