aether-shards/.cursor/rules/ui/CharacterSheet/RULE.md

---
description: Character Sheet UI component - the Explorer's dossier combining stats, inventory, and skill tree
globs: src/ui/components/CharacterSheet.js, src/ui/components/CharacterSheet.ts, src/types/CharacterSheet.ts
alwaysApply: false
---

# **Character Sheet Rule**

The Character Sheet is a UI component used to view and manage an Explorer unit. It combines Stat visualization, Inventory management (Paper Doll), and Skill Tree progression into a single tabbed interface.

## **1. Visual Layout**

Style: High-tech/Fantasy hybrid. Dark semi-transparent backgrounds with voxel-style borders.  
Container: Centered Modal (80% width/height).

### **A. Header (The Identity)**

- **Left:** Large 2D Portrait of the Unit
- **Center:** Name, Class Title (e.g., "Vanguard"), and Level
- **Bottom:** XP Bar (Gold progress fill). Displays "SP: [X]" badge if Skill Points are available
- **Right:** "Close" button (X)

### **B. Left Panel: Attributes (The Data)**

- A vertical list of stats derived from `getEffectiveStat()`
- **Primary:** Health (Bar), AP (Icons)
- **Secondary:** Attack, Defense, Magic, Speed, Willpower, Tech
- **Interaction:** Hovering a stat shows a Tooltip breaking down the value (Base + Gear + Buffs)

### **C. Center Panel: Paper Doll (The Gear)**

- **Visual:** The Unit's 3D model (or 2D silhouette) in the center
- **Slots:** Four large square buttons arranged around the body:
  - **Left:** Primary Weapon
  - **Right:** Off-hand / Relic
  - **Body:** Armor
  - **Accessory:** Utility Device
- **Interaction:** Clicking a slot opens the "Inventory Side-Panel" filtering for that slot type

### **D. Right Panel: Tabs (The Management)**

A tabbed container switching between:

1. **Inventory:** Grid of unequipped items in the squad's backpack
2. **Skills:** Embeds the **Skill Tree** component (Vertical Scrolling)
3. **Mastery:** (Hub Only) Shows progress toward unlocking Tier 2 classes

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

```typescript
// src/types/CharacterSheet.ts

export interface CharacterSheetProps {
  unitId: string;
  readOnly: boolean; // True during enemy turn or restricted events
}

export interface CharacterSheetState {
  unit: Explorer; // The full object
  activeTab: 'INVENTORY' | 'SKILLS' | 'MASTERY';
  selectedSlot: 'WEAPON' | 'ARMOR' | 'RELIC' | 'UTILITY' | null;
}

export interface StatTooltip {
  label: string; // "Attack"
  total: number; // 15
  breakdown: { source: string, value: number }[]; // [{s: "Base", v: 10}, {s: "Rusty Blade", v: 5}]
}
```

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

**CoA 1: Stat Rendering**

- Stats must reflect the _effective_ value
- If a unit has a "Weakness" debuff reducing Attack, the Attack number should appear Red. If buffed, Green

**CoA 2: Equipment Swapping**

- Clicking an Equipment Slot toggles the Right Panel to "Inventory" mode, filtered by that slot type
- Clicking an item in the Inventory immediately equips it, swapping the old item back to the bag
- Stats must verify/update immediately upon equip

**CoA 3: Skill Interaction**

- The Skill Tree tab must display the `SkillTreeUI` component we designed earlier
- Spending an SP in the tree must subtract from the Unit's `skillPoints` and update the view immediately

**CoA 4: Context Awareness**

- In **Dungeon Mode**, the "Inventory" tab acts as the "Run Inventory" (temp loot)
- In **Hub Mode**, the "Inventory" tab acts as the "Stash" (permanent items)

## **4. Implementation Requirements**

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

1. **Layout:** Use CSS Grid to create the 3-column layout (Stats, Paper Doll, Tabs)
2. **Props:** Accept a `unit` object. Watch for changes to re-render stats
3. **Stats Column:** Implement a helper `_renderStat(label, value, breakdown)` that creates a hoverable div with a tooltip
4. **Paper Doll:** Render 4 button slots. If slot is empty, show a ghost icon. If full, show the Item Icon
5. **Tabs:** Implement simple switching logic
   - _Inventory Tab:_ Render a grid of `item-card` elements
   - _Skills Tab:_ Embed `<skill-tree-ui .unit=${this.unit}></skill-tree-ui>`
6. **Events:** Dispatch `equip-item` events when dragging/clicking inventory items

## **5. Integration Strategy**

**Context:** The Character Sheet is a modal that sits above all other UI (CombatHUD, Hub, TeamBuilder). It should be mounted to the `#ui-layer` when triggered and removed when closed.

**Trigger Points:**

- **Combat:** Clicking the Unit Portrait in CombatHUD dispatches `open-character-sheet`
- **Hub:** Clicking a unit card in the Barracks dispatches `open-character-sheet`
- **Input:** Pressing 'C' (configured in InputManager) triggers it for the active unit