Mana-Loop/REFACTORING_PLAN.md

Mana Loop - Component Refactoring Plan

Current State

The main page.tsx file is ~2000+ lines and contains all game logic and rendering in a single component. This makes it:

• Hard to maintain
• Hard to test individual features
• Prone to performance issues (entire component re-renders on any state change)
• Difficult for multiple developers to work on

Proposed Component Structure

Directory: /src/components/game/

Layout Components

GameLayout.tsx       - Main layout wrapper with header/footer
Calendar.tsx         - Day calendar display in header
ResourceBar.tsx      - Day/time/insight display in header

Sidebar Components

ManaSidebar.tsx      - Left sidebar container
ManaDisplay.tsx      - Current mana, max mana, regen display
GatherButton.tsx     - Click-to-gather button with hold functionality
ActionButtons.tsx    - Meditate/Climb/Study/Convert buttons
FloorStatus.tsx      - Current floor display with HP bar

Tab Content Components

SpireTab.tsx         - Main spire/combat tab
├── CurrentFloor.tsx    - Floor info, guardian, HP bar
├── ActiveSpell.tsx     - Active spell details and cast progress
├── StudyProgress.tsx   - Current study progress display
├── KnownSpells.tsx     - Grid of learned spells
└── ActivityLog.tsx     - Game event log

SpellsTab.tsx        - Spell learning tab
├── SpellTier.tsx       - Spells grouped by tier
└── SpellCard.tsx       - Individual spell card

LabTab.tsx           - Elemental mana lab tab
├── ElementalMana.tsx   - Grid of elemental mana
├── ElementConversion.tsx - Convert raw to element
├── UnlockElements.tsx  - Unlock new elements
└── CompositeCrafting.tsx - Craft composite elements

SkillsTab.tsx        - Skill learning tab
├── SkillCategory.tsx   - Skills grouped by category
└── SkillCard.tsx       - Individual skill card

GrimoireTab.tsx      - Prestige upgrades tab
└── PrestigeCard.tsx    - Individual prestige upgrade

StatsTab.tsx         - Detailed stats breakdown
├── ManaStats.tsx       - Mana-related stats
├── CombatStats.tsx     - Combat-related stats
├── StudyStats.tsx      - Study-related stats
└── ActiveUpgrades.tsx  - List of active skill upgrades

Shared Components

SpellCost.tsx        - Formatted spell cost display
DamageBreakdown.tsx  - Damage calculation breakdown
BuffIndicator.tsx    - Active buff/debuff display
UpgradeDialog.tsx    - Skill upgrade selection dialog

Implementation Phases

Phase 1: Extract Simple Components (Low Risk)

• Calendar.tsx
• ActivityLog.tsx
• SpellCost.tsx
• KnownSpells.tsx

Phase 2: Extract Tab Components (Medium Risk)

• SpireTab.tsx
• SpellsTab.tsx
• LabTab.tsx
• SkillsTab.tsx
• GrimoireTab.tsx
• StatsTab.tsx

Phase 3: Extract Sidebar Components (Medium Risk)

• ManaDisplay.tsx
• GatherButton.tsx
• ActionButtons.tsx
• FloorStatus.tsx

Phase 4: Create Shared Hooks

• useGameState.ts - Custom hook for game state access
• useComputedStats.ts - Memoized computed stats
• useSpellCast.ts - Spell casting logic
• useStudy.ts - Skill/spell study logic

Benefits

1. Maintainability: Each component has a single responsibility
2. Performance: React can skip re-rendering unchanged components
3. Testability: Individual components can be tested in isolation
4. Collaboration: Multiple developers can work on different components
5. Code Reuse: Shared components can be used across tabs

Migration Strategy

1. Create new component file
2. Move relevant code from page.tsx
3. Pass required props or use store directly
4. Add TypeScript types
5. Test functionality
6. Remove code from page.tsx
7. Repeat for each component

Estimated Lines of Code Reduction

• Current page.tsx: ~2000 lines
• After refactoring: ~200-300 lines (main layout only)
• Total component files: ~30-40 files averaging 50-100 lines each