Mana-Loop/docs/phase3-refactor-plan.md

Phase 3: Refactor Large Files Plan

Overview

Split files over 300 lines into focused modules. Keep public APIs stable - don't rename exports unless clearly a mistake.

High Priority Files (Audit Findings)

1. src/lib/game/store.ts (2464 lines) - MONOLITHIC LEGACY STORE

Status: Mid-refactor - project has started moving to slice architecture (/stores/ directory) Action: Complete migration to slice-based architecture

• New architecture exists: gameStore.ts, manaStore.ts, skillStore.ts, combatStore.ts, prestigeStore.ts
• Migrate all remaining imports from store.ts to new stores
• Deprecate and eventually remove store.ts
• Complexity: 3+ steps → Requires sub-agent delegation

2. src/lib/game/skill-evolution.ts (2312 lines) - ALL SKILL TREES

Action: Split by skill category

• Separate files for: mana skills, combat skills, study skills, element skills
• Extract helper functions (createPerk, createUpgrade, etc.) to skill-utils.ts
• Keep SKILL_EVOLUTION_PATHS as the main export
• Complexity: 3+ steps → Requires sub-agent delegation

3. src/lib/game/constants.ts (1436 lines) - MIXED CONSTANTS

Action: Split into domain-specific files

• elements.ts (element definitions)
• guardians.ts (guardian definitions)
• spells.ts (spell definitions)
• skills.ts (skill definitions)
• prestige.ts (prestige definitions)
• room-config.ts (room types, swarm config, etc.)
• Keep constants.ts as barrel file exporting from all split files
• Complexity: 3+ steps → Requires sub-agent delegation

4. src/lib/game/data/enchantment-effects.ts (846 lines) - ENCHANTMENT DATA

Action: Split by category or move data to JSON

• Separate files: spell-enchants.ts, mana-enchants.ts, combat-enchants.ts, etc.
• Keep ENCHANTMENT_EFFECTS as main export
• Complexity: 2-3 steps → Consider sub-agent

5. src/components/game/tabs/CraftingTab.tsx (965 lines) - CRAFTING UI

Action: Split by crafting stage

• EnchantmentDesigner.tsx (design stage)
• EnchantmentPreparer.tsx (prepare stage)
• EnchantmentApplier.tsx (apply stage)
• EquipmentCrafter.tsx (craft stage)
• Keep CraftingTab.tsx as coordinator
• Complexity: 2-3 steps → Consider sub-agent

Medium Priority Files

6. src/lib/game/types.ts (516 lines) - TYPE DEFINITIONS

Action: Split into domain-specific type files

• types/elements.ts, types/attunements.ts, types/spells.ts, etc.
• Keep types/index.ts as barrel file

7. src/lib/game/computed-stats.ts (492 lines) - MIXED UTILITIES

Action: Split by responsibility

• formatting.ts (fmt, fmtDec)
• floor-utils.ts (floor HP, floor element)
• mana-utils.ts (computeMaxMana, computeRegen, etc.)
• combat-utils.ts (calcDamage, calcInsight, etc.)

8. src/lib/game/utils.ts (372 lines) - MIXED UTILITIES

Action: Same as computed-stats.ts - split by responsibility

Low Priority Files (Acceptable Size/Structure)

• src/lib/game/stores/gameStore.ts (509 lines) - Good coordinator
• src/lib/game/store/craftingSlice.ts (644 lines) - Well-structured slice
• src/components/game/tabs/DebugTab.tsx (700 lines) - Debug UI, can split if desired
• src/app/page.tsx (465 lines) - Main page, could lazy load tabs

Guidelines

1. Keep public APIs stable - don't rename exports unless mistake
2. Don't change game balance values
3. Don't refactor working code just for style
4. Don't introduce new dependencies
5. When in doubt, flag it and move on
6. Verify build after each file split
7. Commit regularly

Execution Order

1. Start with store.ts (highest priority, completes architecture migration)
2. Then skill-evolution.ts (second largest)
3. Then constants.ts (mixed constants)
4. Other files as time permits

Verification

• Run npm run build after each refactoring step
• Run npm run test if tests exist
• Commit changes regularly with descriptive messages