docs: Add README.md, update AGENTS.md, audit report, and massive refactoring

Documentation: - Add comprehensive README.md with project overview - Update AGENTS.md with new file structure and slice pattern - Add AUDIT_REPORT.md documenting unimplemented effects Refactoring (page.tsx: 1695 → 434 lines, 74% reduction): - Extract SkillsTab.tsx component - Extract StatsTab.tsx component - Extract UpgradeDialog.tsx component - Move getDamageBreakdown and getTotalDPS to computed-stats.ts - Move ELEMENT_ICON_NAMES to constants.ts All lint checks pass, functionality preserved.
2026-03-26 13:01:29 +00:00
parent 2ca5d8b7f8
commit 315490cedb
13 changed files with 2340 additions and 1536 deletions
--- a/AUDIT_REPORT.md
+++ b/AUDIT_REPORT.md
@@ -0,0 +1,313 @@
+# Mana Loop - Codebase Audit Report
+
+**Task ID:** 4  
+**Date:** Audit of unimplemented effects, upgrades, and missing functionality
+
+---
+
+## 1. Special Effects Status
+
+### SPECIAL_EFFECTS Constant (upgrade-effects.ts)
+
+The `SPECIAL_EFFECTS` constant defines 32 special effect IDs. Here's the implementation status:
+
+| Effect ID | Name | Status | Notes |
+|-----------|------|--------|-------|
+| `MANA_CASCADE` | Mana Cascade | ⚠️ Partially Implemented | Defined in `computeDynamicRegen()` but that function is NOT called from store.ts |
+| `STEADY_STREAM` | Steady Stream | ⚠️ Partially Implemented | Defined in `computeDynamicRegen()` but not called from tick |
+| `MANA_TORRENT` | Mana Torrent | ⚠️ Partially Implemented | Defined in `computeDynamicRegen()` but not called |
+| `FLOW_SURGE` | Flow Surge | ❌ Missing | Not implemented anywhere |
+| `MANA_EQUILIBRIUM` | Mana Equilibrium | ❌ Missing | Not implemented |
+| `DESPERATE_WELLS` | Desperate Wells | ⚠️ Partially Implemented | Defined in `computeDynamicRegen()` but not called |
+| `MANA_ECHO` | Mana Echo | ❌ Missing | Not implemented in gatherMana() |
+| `EMERGENCY_RESERVE` | Emergency Reserve | ❌ Missing | Not implemented in startNewLoop() |
+| `BATTLE_FURY` | Battle Fury | ⚠️ Partially Implemented | In `computeDynamicDamage()` but function not called |
+| `ARMOR_PIERCE` | Armor Pierce | ❌ Missing | Floor defense not implemented |
+| `OVERPOWER` | Overpower | ✅ Implemented | store.ts line 627 |
+| `BERSERKER` | Berserker | ✅ Implemented | store.ts line 632 |
+| `COMBO_MASTER` | Combo Master | ❌ Missing | Not implemented |
+| `ADRENALINE_RUSH` | Adrenaline Rush | ❌ Missing | Not implemented on enemy defeat |
+| `PERFECT_MEMORY` | Perfect Memory | ❌ Missing | Not implemented in cancel study |
+| `QUICK_MASTERY` | Quick Mastery | ❌ Missing | Not implemented |
+| `PARALLEL_STUDY` | Parallel Study | ⚠️ Partially Implemented | State exists but logic incomplete |
+| `STUDY_INSIGHT` | Study Insight | ❌ Missing | Not implemented |
+| `STUDY_MOMENTUM` | Study Momentum | ❌ Missing | Not implemented |
+| `KNOWLEDGE_ECHO` | Knowledge Echo | ❌ Missing | Not implemented |
+| `KNOWLEDGE_TRANSFER` | Knowledge Transfer | ❌ Missing | Not implemented |
+| `MENTAL_CLARITY` | Mental Clarity | ❌ Missing | Not implemented |
+| `STUDY_REFUND` | Study Refund | ❌ Missing | Not implemented |
+| `FREE_STUDY` | Free Study | ❌ Missing | Not implemented |
+| `MIND_PALACE` | Mind Palace | ❌ Missing | Not implemented |
+| `STUDY_RUSH` | Study Rush | ❌ Missing | Not implemented |
+| `CHAIN_STUDY` | Chain Study | ❌ Missing | Not implemented |
+| `ELEMENTAL_HARMONY` | Elemental Harmony | ❌ Missing | Not implemented |
+| `DEEP_STORAGE` | Deep Storage | ❌ Missing | Not implemented |
+| `DOUBLE_CRAFT` | Double Craft | ❌ Missing | Not implemented |
+| `ELEMENTAL_RESONANCE` | Elemental Resonance | ❌ Missing | Not implemented |
+| `PURE_ELEMENTS` | Pure Elements | ❌ Missing | Not implemented |
+
+**Summary:** 2 fully implemented, 6 partially implemented (function exists but not called), 24 not implemented.
+
+---
+
+## 2. Enchantment Effects Status
+
+### Equipment Enchantment Effects (enchantment-effects.ts)
+
+The following effect types are defined:
+
+| Effect Type | Status | Notes |
+|-------------|--------|-------|
+| **Spell Effects** (`type: 'spell'`) | ✅ Working | Spells granted via `getSpellsFromEquipment()` |
+| **Bonus Effects** (`type: 'bonus'`) | ✅ Working | Applied in `computeEquipmentEffects()` |
+| **Multiplier Effects** (`type: 'multiplier'`) | ✅ Working | Applied in `computeEquipmentEffects()` |
+| **Special Effects** (`type: 'special'`) | ⚠️ Tracked Only | Added to `specials` Set but NOT applied in game logic |
+
+### Special Enchantment Effects Not Applied:
+
+| Effect ID | Description | Issue |
+|-----------|-------------|-------|
+| `spellEcho10` | 10% chance cast twice | Tracked but not implemented in combat |
+| `lifesteal5` | 5% damage as mana | Tracked but not implemented in combat |
+| `overpower` | +50% damage at 80% mana | Tracked but separate from skill upgrade version |
+
+**Location of Issue:**
+```typescript
+// effects.ts line 58-60
+} else if (effect.type === 'special' && effect.specialId) {
+  specials.add(effect.specialId);
+}
+// Effect is tracked but never used in combat/damage calculations
+```
+
+---
+
+## 3. Skill Effects Status
+
+### SKILLS_DEF Analysis (constants.ts)
+
+Skills with direct effects that should apply per level:
+
+| Skill | Effect | Status |
+|-------|--------|--------|
+| `manaWell` | +100 max mana per level | ✅ Implemented |
+| `manaFlow` | +1 regen/hr per level | ✅ Implemented |
+| `elemAttune` | +50 elem mana cap | ✅ Implemented |
+| `manaOverflow` | +25% click mana | ✅ Implemented |
+| `quickLearner` | +10% study speed | ✅ Implemented |
+| `focusedMind` | -5% study cost | ✅ Implemented |
+| `meditation` | 2.5x regen after 4hrs | ✅ Implemented |
+| `knowledgeRetention` | +20% progress saved | ⚠️ Partially Implemented |
+| `enchanting` | Unlocks designs | ✅ Implemented |
+| `efficientEnchant` | -5% capacity cost | ⚠️ Not verified |
+| `disenchanting` | 20% mana recovery | ⚠️ Not verified |
+| `enchantSpeed` | -10% enchant time | ⚠️ Not verified |
+| `scrollCrafting` | Create scrolls | ❌ Not implemented |
+| `essenceRefining` | +10% effect power | ⚠️ Not verified |
+| `effCrafting` | -10% craft time | ⚠️ Not verified |
+| `fieldRepair` | +15% repair | ❌ Repair not implemented |
+| `elemCrafting` | +25% craft output | ✅ Implemented |
+| `manaTap` | +1 mana/click | ✅ Implemented |
+| `manaSurge` | +3 mana/click | ✅ Implemented |
+| `manaSpring` | +2 regen | ✅ Implemented |
+| `deepTrance` | 3x after 6hrs | ✅ Implemented |
+| `voidMeditation` | 5x after 8hrs | ✅ Implemented |
+| `insightHarvest` | +10% insight | ✅ Implemented |
+| `temporalMemory` | Keep spells | ✅ Implemented |
+| `guardianBane` | +20% vs guardians | ⚠️ Tracked but not verified |
+
+---
+
+## 4. Missing Implementations
+
+### 4.1 Dynamic Effect Functions Not Called
+
+The following functions exist in `upgrade-effects.ts` but are NOT called from `store.ts`:
+
+```typescript
+// upgrade-effects.ts - EXISTS but NOT USED
+export function computeDynamicRegen(
+  effects: ComputedEffects,
+  baseRegen: number,
+  maxMana: number,
+  currentMana: number,
+  incursionStrength: number
+): number { ... }
+
+export function computeDynamicDamage(
+  effects: ComputedEffects,
+  baseDamage: number,
+  floorHPPct: number,
+  currentMana: number,
+  maxMana: number,
+  consecutiveHits: number
+): number { ... }
+```
+
+**Where it should be called:**
+- `store.ts` tick() function around line 414 for regen
+- `store.ts` tick() function around line 618 for damage
+
+### 4.2 Missing Combat Special Effects
+
+Location: `store.ts` tick() combat section (lines 510-760)
+
+Missing implementations:
+```typescript
+// BATTLE_FURY - +10% damage per consecutive hit
+if (hasSpecial(effects, SPECIAL_EFFECTS.BATTLE_FURY)) {
+  // Need to track consecutiveHits in state
+}
+
+// ARMOR_PIERCE - Ignore 10% floor defense
+// Floor defense not implemented in game
+
+// COMBO_MASTER - Every 5th attack deals 3x damage
+if (hasSpecial(effects, SPECIAL_EFFECTS.COMBO_MASTER)) {
+  // Need to track hitCount in state
+}
+
+// ADRENALINE_RUSH - Restore 5% mana on kill
+// Should be added after floorHP <= 0 check
+```
+
+### 4.3 Missing Study Special Effects
+
+Location: `store.ts` tick() study section (lines 440-485)
+
+Missing implementations:
+```typescript
+// MENTAL_CLARITY - +10% study speed when mana > 75%
+// STUDY_RUSH - First hour is 2x speed
+// STUDY_REFUND - 25% mana back on completion
+// KNOWLEDGE_ECHO - 10% instant study chance
+// STUDY_MOMENTUM - +5% speed per consecutive hour
+```
+
+### 4.4 Missing Loop/Click Effects
+
+Location: `store.ts` gatherMana() and startNewLoop()
+
+```typescript
+// gatherMana() - MANA_ECHO
+// 10% chance to gain double mana from clicks
+if (hasSpecial(effects, SPECIAL_EFFECTS.MANA_ECHO) && Math.random() < 0.1) {
+  cm *= 2;
+}
+
+// startNewLoop() - EMERGENCY_RESERVE
+// Keep 10% max mana when starting new loop
+if (hasSpecial(effects, SPECIAL_EFFECTS.EMERGENCY_RESERVE)) {
+  newState.rawMana = maxMana * 0.1;
+}
+```
+
+### 4.5 Parallel Study Incomplete
+
+`parallelStudyTarget` exists in state but the logic is not fully implemented in tick():
+- State field exists (line 203)
+- No tick processing for parallel study
+- UI may show it but actual progress not processed
+
+---
+
+## 5. Balance Concerns
+
+### 5.1 Weak Upgrades
+
+| Upgrade | Issue | Suggestion |
+|---------|-------|------------|
+| `manaThreshold` | +20% mana for -10% regen is a net negative early | Change to +30% mana for -5% regen |
+| `manaOverflow` | +25% click mana at 5 levels is only +5%/level | Increase to +10% per level |
+| `fieldRepair` | Repair system not implemented | Remove or implement repair |
+| `scrollCrafting` | Scroll system not implemented | Remove or implement scrolls |
+
+### 5.2 Tier Scaling Issues
+
+From `skill-evolution.ts`, tier multipliers are 10x per tier:
+- Tier 1: multiplier 1
+- Tier 2: multiplier 10
+- Tier 3: multiplier 100
+- Tier 4: multiplier 1000
+- Tier 5: multiplier 10000
+
+This creates massive power jumps that may trivialize content when tiering up.
+
+### 5.3 Special Effect Research Costs
+
+Research skills for effects are expensive but effects may not be implemented:
+- `researchSpecialEffects` costs 500 mana + 10 hours study
+- Effects like `spellEcho10` are tracked but not applied
+- Player invests resources for non-functional upgrades
+
+---
+
+## 6. Critical Issues
+
+### 6.1 computeDynamicRegen Not Used
+
+**File:** `computed-stats.ts` lines 210-225
+
+The function exists but only applies incursion penalty. It should call the more comprehensive `computeDynamicRegen` from `upgrade-effects.ts` that handles:
+- Mana Cascade
+- Mana Torrent
+- Desperate Wells
+- Steady Stream
+
+### 6.2 No Consecutive Hit Tracking
+
+`BATTLE_FURY` and `COMBO_MASTER` require tracking consecutive hits, but this state doesn't exist. Need:
+```typescript
+// In GameState
+consecutiveHits: number;
+totalHitsThisLoop: number;
+```
+
+### 6.3 Enchantment Special Effects Not Applied
+
+The `specials` Set is populated but never checked in combat for enchantment-specific effects like:
+- `lifesteal5`
+- `spellEcho10`
+
+---
+
+## 7. Recommendations
+
+### Priority 1 - Core Effects
+1. Call `computeDynamicRegen()` from tick() instead of inline calculation
+2. Call `computeDynamicDamage()` from combat section
+3. Implement MANA_ECHO in gatherMana()
+4. Implement EMERGENCY_RESERVE in startNewLoop()
+
+### Priority 2 - Combat Effects
+1. Add `consecutiveHits` to GameState
+2. Implement BATTLE_FURY damage scaling
+3. Implement COMBO_MASTER every 5th hit
+4. Implement ADRENALINE_RUSH on kill
+
+### Priority 3 - Study Effects
+1. Implement MENTAL_CLARITY conditional speed
+2. Implement STUDY_RUSH first hour bonus
+3. Implement STUDY_REFUND on completion
+4. Implement KNOWLEDGE_ECHO instant chance
+
+### Priority 4 - Missing Systems
+1. Implement or remove `scrollCrafting` skill
+2. Implement or remove `fieldRepair` skill
+3. Complete parallel study tick processing
+4. Implement floor defense for ARMOR_PIERCE
+
+---
+
+## 8. Files Affected
+
+| File | Changes Needed |
+|------|----------------|
+| `src/lib/game/store.ts` | Call dynamic effect functions, implement specials |
+| `src/lib/game/computed-stats.ts` | Integrate with upgrade-effects dynamic functions |
+| `src/lib/game/types.ts` | Add consecutiveHits to GameState |
+| `src/lib/game/skill-evolution.ts` | Consider removing unimplementable upgrades |
+
+---
+
+**End of Audit Report**