# SPEC: Mana Conversion Attunement Fix

## 1. Objective
Fix the mana conversion logic for attunements (e.g., Enchanter Transference) that incorrectly deducts mana from the player's mana pool every tick instead of reducing raw mana regen. This bug causes players to get stuck at 1 mana below their mana cap.

**Why**:
- Current behavior breaks core mana progression loop
- Players cannot reach full mana capacity when attunements are active
- Violates intended design where attunement costs should reduce regen rate, not drain pool

## 2. Controls/API
No new player-facing controls or APIs are added. This is an internal logic fix.

### Modified Game Internals:
- `computeRegen()` / `computeEffectiveRegen()` in `computed-stats.ts`: Adjust to account for attunement regen reductions
- `manaStore.ts` tick logic: Remove direct mana pool deductions for attunement costs
- Attunement effect application: Add regen reduction to unified effect system instead of pool deductions
- Game tick loop: Ensure regen reduction is applied before mana regen calculation

### Public API Changes:
None (internal bug fix only)

## 3. Project Layout
Follow existing modular architecture rules from AGENTS.md:

### Files to Modify:
| File | Purpose | Line Count Check |
|------|---------|------------------|
| `src/lib/game/stores/manaStore.ts` | Remove pool deduction logic for attunements, ensure regen reduction applied | Must stay <400 lines |
| `src/lib/game/computed-stats.ts` | Update `computeRegen()` to apply attunement regen reductions from unified effects | Must stay <400 lines |
| `src/lib/game/effects.ts` | Add attunement regen reduction to unified effect system if not already present | Must stay <400 lines |
| `src/lib/game/stores/gameLoopActions.ts` | Ensure correct tick order: apply regen reductions → calculate regen → update mana pool | Must stay <400 lines |
| `src/lib/game/constants/attunements.ts` (or similar) | Verify attunement effect definitions use regen reduction instead of pool drain | Must stay <400 lines |

### Files to Create:
| File | Purpose | Line Count Check |
|------|---------|------------------|
| `src/lib/game/stores/__tests__/mana-conversion-fix.test.ts` | Regression test for fix | Must stay <400 lines |

### Module Ownership:
- Mana logic: `manaStore.ts` (store module)
- Computed stats: `computed-stats.ts` (shared utility)
- Effects: `effects.ts` (unified effect system)
- Tests: `stores/__tests__/` (test directory)

## 4. Code Style
Follow existing project conventions:
- TypeScript strict mode, explicit type annotations for game state
- Zustand store patterns: `set()`, `get()` for state updates, avoid direct mutations
- Unified effect system: All stat modifications flow through `getUnifiedEffects()`
- Naming: camelCase for variables/functions, PascalCase for interfaces/types
- No `any` types, use defined interfaces from `src/lib/game/types.ts`
- Follow ESLint rules (run `npm run lint` before committing)
- Use existing patterns for regen/reduction calculations (e.g., `regenBonus`, `regenMultiplier` in unified effects)

## 5. Testing
### What to Test:
1. **Mana regen with active attunements**: Verify attunement costs reduce regen rate, not mana pool
2. **Mana cap behavior**: Player can reach full mana cap when attunements are active
3. **No pool drain**: Mana pool is never deducted directly by attunement costs
4. **Unified effect integration**: Attunement regen reductions are properly included in `getUnifiedEffects()`
5. **Tick order**: Regen reductions are applied before mana regen calculation in game tick

### How to Test:
- Unit tests using Vitest (existing test framework)
- Test files located in `src/lib/game/stores/__tests__/`
- Mock game state to simulate active attunements
- Assert regen values and mana pool behavior
- Run `npm run test` to execute all tests

### Tooling:
- Vitest (test runner)
- Zustand store testing patterns (use `getState()` for assertions)
- Mock `getUnifiedEffects()` to return attunement regen reductions

## 6. Boundaries (Out-of-Scope Items)
- No changes to attunement definitions (only their effect application)
- No new attunements or mana types added
- No changes to combat, crafting, or prestige systems (unless directly related to mana regen)
- No UI changes (this is internal logic only)
- No modifications to legacy `store.ts` (use modular stores only)
- No changes to banned content rules or mana type hierarchy

## Acceptance Criteria (Per Requirement)
| Requirement | Acceptance Criterion |
|-------------|----------------------|
| Attunement costs reduce raw mana regen instead of deducting from pool | Unit test passes: `computeRegen()` returns reduced value when attunement regen reduction is applied |
| Deduction applied before mana regen calculations | Unit test passes: Game tick applies regen reduction before calculating mana addition to pool |
| Mana pool no longer stuck below cap | Integration test passes: Mana pool reaches full cap when attunements are active after sufficient time |
| No direct mana pool deductions from attunements | Code review: No calls to `spendRawMana()` or direct `rawMana` deductions in attunement logic |
| Follow unified effect system | Code review: Attunement regen reductions are added to `UnifiedEffects` interface and applied via `getUnifiedEffects()` |
| All files stay under 400 lines | Pre-commit hook passes: No modified files exceed 400 lines |
| Regression test added | Test file exists and runs successfully in `npm run test` |