aether-shards/specs/Character_Sheet.spec.md

Character Sheet Specification: The Explorer's Dossier

This document defines the 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)

// 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. Prompt for Coding Agent

"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.