Mana-Loop/docs/SPEC-mana-conversion-fix.md

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