feat: add prestige system and skill upgrades with comprehensive documentation

src/lib/game/hooks/useGameDerived.ts

@@ -17,7 +17,7 @@ import {
   getElementalBonus,
 } from '../store/computed';
 import { ELEMENTS, GUARDIANS, SPELLS_DEF, getStudySpeedMultiplier, getStudyCostMultiplier, HOURS_PER_TICK, TICK_MS } from '../constants';
-import { hasSpecial, SPECIAL_EFFECTS } from '../upgrade-effects';
+import { hasSpecial, SPECIAL_EFFECTS } from '../special-effects';
 
 /**
  * Hook for all mana-related derived stats

src/lib/game/hooks/useSkillUpgradeSelection.ts

@@ -0,0 +1,52 @@
+// ─── Skill Upgrade Selection Hook ────────────────────────
+// Hook for managing milestone upgrade selection state in SkillsTab
+
+import { useState, useMemo, useCallback, SetStateAction, Dispatch } from 'react';
+import type { SkillUpgradeChoice } from '@/lib/game/types';
+
+export interface UseSkillUpgradeSelectionResult {
+  pendingSelections: string[];
+  setPendingSelections: Dispatch<SetStateAction<string[]>>;
+  toggleUpgrade: (upgradeId: string, available: SkillUpgradeChoice[], alreadySelected: string[]) => void;
+  handleConfirm: (upgradeDialogSkill: string | null, upgradeDialogMilestone: 5 | 10, commitSkillUpgrades: (skillId: string, selections: string[], milestone: 5 | 10) => void, onClose: () => void) => void;
+  handleCancel: (onClose: () => void) => void;
+}
+
+/**
+ * Hook for managing skill upgrade selection state in the SkillsTab milestone upgrade dialog.
+ * Manages pending selections across the dialog open/close cycle.
+ */
+export function useSkillUpgradeSelection(): UseSkillUpgradeSelectionResult {
+  const [pendingSelections, setPendingSelections] = useState<string[]>([]);
+
+  const toggleUpgrade = useCallback((upgradeId: string, available: SkillUpgradeChoice[], alreadySelected: string[]) => {
+    const currentSelections = pendingSelections.length > 0 ? pendingSelections : alreadySelected;
+    if (currentSelections.includes(upgradeId)) {
+      setPendingSelections(currentSelections.filter(id => id !== upgradeId));
+    } else if (currentSelections.length < 2) {
+      setPendingSelections([...currentSelections, upgradeId]);
+    }
+  }, [pendingSelections]);
+
+  const handleConfirm = useCallback((upgradeDialogSkill: string | null, upgradeDialogMilestone: 5 | 10, commitSkillUpgrades: (skillId: string, selections: string[], milestone: 5 | 10) => void, onClose: () => void) => {
+    const currentSelections = pendingSelections.length > 0 ? pendingSelections : [];
+    if (currentSelections.length === 2 && upgradeDialogSkill) {
+      commitSkillUpgrades(upgradeDialogSkill, currentSelections, upgradeDialogMilestone);
+    }
+    setPendingSelections([]);
+    onClose();
+  }, [pendingSelections]);
+
+  const handleCancel = useCallback((onClose: () => void) => {
+    setPendingSelections([]);
+    onClose();
+  }, []);
+
+  return useMemo(() => ({
+    pendingSelections,
+    setPendingSelections,
+    toggleUpgrade,
+    handleConfirm,
+    handleCancel,
+  }), [pendingSelections, toggleUpgrade, handleConfirm, handleCancel]);
+}