playlist-data-engine 1.1.0

package/dist/core/progression/LevelUpProcessor.d.ts

@@ -0,0 +1,234 @@
+/**
+ * LevelUpProcessor - Handles character leveling mechanics
+ * Based on specs/001-core-engine/SPEC.md and D&D 5e rules
+ *
+ * Uses FeatureQuery for class feature lookup.
+ * - Replaces hardcoded getClassFeaturesForLevel() with FeatureQuery lookup
+ * - Validates prerequisite chains on level up
+ * - Applies new feature effects when leveling up
+ * - Handles conditional features (player choice)
+ * - Returns feature IDs instead of display strings
+ */
+import type { CharacterSheet, Ability } from '../types/Character.js';
+import type { StatManager } from './stat/StatManager.js';
+/**
+ * Level-up benefits returned after processing a level-up
+ */
+export interface LevelUpBenefits {
+    newLevel: number;
+    hitPointIncrease: number;
+    newHitPointsTotal: number;
+    proficiencyBonusIncrease: number;
+    newProficiencyBonus: number;
+    /** New: Support multiple stat increases */
+    abilityScoreIncreases?: Array<{
+        ability: Ability;
+        increase: number;
+    }>;
+    /** Deprecated: Kept for backward compatibility */
+    abilityScoreIncrease?: {
+        ability: Ability;
+        increase: number;
+    };
+    newSpellSlots?: Record<number, {
+        total: number;
+        used: number;
+    }>;
+    /**
+     * Class features gained at this level
+     * Returns feature IDs instead of display strings
+     * OLD: ['Barbarian Level 2', 'Reckless Attack']
+     * NEW: ['reckless_attack', 'danger_sense']
+     */
+    classFeatures?: string[];
+    /**
+     * Feature effects applied during level-up
+     * Stores effects that were applied to the character
+     */
+    featureEffects?: Array<{
+        featureId: string;
+        featureName: string;
+        effectsApplied: number;
+    }>;
+}
+/**
+ * Configuration for uncapped mode progression
+ * Provide formulas that work for ALL levels (1-infinity), not just beyond 20
+ */
+export interface UncappedProgressionConfig {
+    /** Custom formula for calculating XP threshold for ANY level */
+    xpFormula?: (level: number) => number;
+    /** Custom formula for calculating proficiency bonus for ANY level */
+    proficiencyBonusFormula?: (level: number) => number;
+}
+/**
+ * LevelUpProcessor class - Processes character level-ups
+ * Handles HP increases, ability score improvements, spell slots, and features
+ */
+export declare class LevelUpProcessor {
+    /** Optional StatManager for advanced stat increase handling */
+    private static statManager?;
+    /** Optional configuration for uncapped mode progression */
+    private static uncappedConfig?;
+    /**
+     * Set configuration for uncapped mode progression
+     * @param config - Configuration with optional custom formulas
+     */
+    static setUncappedConfig(config: UncappedProgressionConfig): void;
+    /**
+     * Get the current uncapped configuration
+     */
+    static getUncappedConfig(): UncappedProgressionConfig | undefined;
+    /**
+     * Set the StatManager instance for stat increase handling
+     * Call this before processing level-ups to enable smart stat selection
+     *
+     * @param statManager - The StatManager instance to use
+     */
+    static setStatManager(statManager: StatManager): void;
+    /**
+     * Get the current StatManager instance
+     */
+    static getStatManager(): StatManager | undefined;
+    /**
+     * Process a character level-up
+     * @param character - The character to level up
+     * @param newLevel - The new level (should be previous level + 1 for normal progression)
+     * @param seed - Optional seed for deterministic HP rolls
+     * @returns Benefits granted by leveling up
+     */
+    static processLevelUp(character: CharacterSheet, newLevel: number, seed?: string): LevelUpBenefits;
+    /**
+     * Get class features gained at a specific level for a character
+     * Uses FeatureQuery to look up features and validates prerequisites
+     *
+     * @param character - The character to check features for
+     * @param characterClass - The character class
+     * @param level - The level to get features for
+     * @returns Array of ClassFeature objects gained at this level
+     */
+    private static getClassFeaturesForLevel;
+    /**
+     * Apply a level-up to a character
+     * @param character - The character to level up
+     * @param benefits - Benefits from processLevelUp
+     * @returns Updated character
+     */
+    static applyLevelUp(character: CharacterSheet, benefits: LevelUpBenefits): CharacterSheet;
+    /**
+     * Calculate HP increase for a level
+     * @param hitDie - The hit die size (d6, d8, d10, d12)
+     * @param conModifier - Constitution modifier
+     * @param seed - Optional seed for deterministic rolling
+     * @returns HP increase
+     */
+    private static calculateHPIncrease;
+    /**
+     * Check if a class is a spellcaster
+     * @param characterClass - The character class
+     * @returns True if the class can cast spells
+     */
+    private static isSpellcaster;
+    /**
+     * Calculate spell slots for a level
+     * Based on D&D 5e spell slot progression
+     * @param characterClass - The character class
+     * @param level - The character level
+     * @returns Record of spell slots by level
+     */
+    private static calculateSpellSlots;
+    /**
+     * Get spell slot count for a specific slot level
+     * Simplified version - would be expanded in full implementation
+     * @param characterLevel - The character level
+     * @param slotLevel - The spell slot level (1-9)
+     * @returns Number of slots available
+     */
+    private static getSpellSlotCount;
+    /**
+     * Get the XP threshold for a specific level
+     * - Standard mode: Uses D&D 5e tables (levels 1-20 only)
+     * - Uncapped mode with custom formula: Uses your formula for ALL levels
+     * - Uncapped mode without custom formula: Continues D&D 5e pattern naturally
+     * @param level - The level
+     * @param isUncapped - Whether this is for uncapped mode
+     * @returns XP required to reach that level
+     */
+    static getXPThreshold(level: number, isUncapped?: boolean): number;
+    /**
+     * Get the proficiency bonus for a specific level
+     * - Standard mode: Uses D&D 5e tables (levels 1-20 only)
+     * - Uncapped mode with custom formula: Uses your formula for ALL levels
+     * - Uncapped mode without custom formula: Continues D&D 5e pattern (+1 every 4 levels)
+     * @param level - The level
+     * @param isUncapped - Whether this is for uncapped mode
+     * @returns Proficiency bonus for that level
+     */
+    static getProficiencyBonus(level: number, isUncapped?: boolean): number;
+    /**
+     * Calculate level from total XP
+     * @param totalXP - Total experience points
+     * @param isUncapped - Whether this is for uncapped mode (allows infinite levels)
+     * @returns Character level
+     */
+    static calculateLevel(totalXP: number, isUncapped?: boolean): number;
+    /**
+     * Get XP needed to reach next level
+     * @param currentLevel - Current character level
+     * @param isUncapped - Whether this is for uncapped mode
+     * @returns XP needed to advance to next level, or 0 if at max (or if uncapped, always returns next threshold)
+     */
+    static getXPToNextLevel(currentLevel: number, isUncapped?: boolean): number;
+    /**
+     * Get progress to next level as a percentage
+     * @param currentLevel - Current level
+     * @param currentXP - Total XP within level thresholds
+     * @param isUncapped - Whether this is for uncapped mode
+     * @returns Percentage (0-100) towards next level
+     */
+    static getProgressPercentage(currentLevel: number, currentXP: number, isUncapped?: boolean): number;
+    /**
+     * Process level-up without stat increases
+     * Used for pending level-up system where stats are applied later
+     *
+     * @param character - The character to level up
+     * @param newLevel - The new level
+     * @param seed - Optional seed for deterministic HP rolls
+     * @returns Benefits without stat increases
+     */
+    static processLevelUpWithoutStats(character: CharacterSheet, newLevel: number, seed?: string): Omit<LevelUpBenefits, 'abilityScoreIncreases' | 'abilityScoreIncrease'>;
+    /**
+     * Apply automatic level-up benefits (HP, proficiency, features, spell slots)
+     * Does NOT apply stat increases
+     *
+     * @param character - The character to update
+     * @param benefits - Benefits without stat increases
+     * @returns Updated character
+     */
+    static applyAutomaticBenefitsOnly(character: CharacterSheet, benefits: Omit<LevelUpBenefits, 'abilityScoreIncreases' | 'abilityScoreIncrease'>): CharacterSheet;
+    /**
+     * Apply ONLY stat increases to a character
+     * Used when completing a pending level-up
+     *
+     * @param character - The character to update
+     * @param statIncreases - Array of stat increases to apply
+     * @returns Updated character
+     */
+    static applyStatIncreasesOnly(character: CharacterSheet, statIncreases: Array<{
+        ability: Ability;
+        amount: number;
+    }>): CharacterSheet;
+    /**
+     * Re-apply all equipment effects after a level-up
+     * Ensures equipment effects persist when character stats change
+     *
+     * This method uses EquipmentEffectApplier's reapplyEquipmentEffects which:
+     * - Clears the equipment_effects array
+     * - Re-applies all properties, features, skills, and spells
+     * - Rebuilds the equipment_effects tracking array
+     *
+     * @param character - The character to reapply equipment effects to
+     */
+    private static reapplyEquipmentEffects;
+}
+//# sourceMappingURL=LevelUpProcessor.d.ts.map

package/dist/core/progression/LevelUpProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LevelUpProcessor.d.ts","sourceRoot":"","sources":["../../../src/core/progression/LevelUpProcessor.ts"],"names":[],"mappings":"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"}

package/dist/core/progression/PrestigeSystem.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Prestige System - Core prestige logic for track mastery
+ *
+ * Handles the prestige mechanic where players reset their character after mastering
+ * a track in exchange for visual badge upgrades.
+ *
+ * Features:
+ * - 10 prestige levels (Roman numerals I-X)
+ * - 1.5x scaling for plays: Prestige 0=10, I=15, II=23, III=34, IV=51, V=77, VI=115, VII=173, VIII=259, IX=389, X=584
+ * - 1.5x scaling for XP: Prestige 0=1,000, I=1,500, II=2,250, III=3,375, IV=5,063, V=7,594, VI=11,391, VII=17,086, VIII=25,629, IX=38,444, X=57,666
+ * - Dual requirement (plays AND XP) prevents "cheesing" the system
+ * - Custom threshold override support for manual control
+ */
+import { type PrestigeLevel, type PrestigeInfo, type PrestigeResult, type CustomThresholds } from '../types/Prestige.js';
+/**
+ * PrestigeSystem handles all prestige-related calculations and logic.
+ *
+ * @example
+ * ```typescript
+ * // Check if a track is mastered
+ * const isMastered = PrestigeSystem.isMastered(15, 2000, 1);
+ *
+ * // Get full prestige info for UI
+ * const info = PrestigeSystem.getPrestigeInfo(1, 15, 2000);
+ *
+ * // Set custom thresholds
+ * PrestigeSystem.setCustomThresholds(5, { playsThreshold: 100, xpThreshold: 10000 });
+ * ```
+ */
+export declare class PrestigeSystem {
+    /**
+     * Custom thresholds that override calculated defaults
+     * Map<prestigeLevel, CustomThresholds>
+     */
+    private static customThresholds;
+    /**
+     * Get the plays threshold for a given prestige level.
+     * Returns custom threshold if set, otherwise calculates using 1.5x scaling.
+     *
+     * Calculated values:
+     * - Prestige 0: 10 plays
+     * - Prestige I: 15 plays
+     * - Prestige II: 23 plays
+     * - Prestige III: 34 plays
+     * - Prestige IV: 51 plays
+     * - Prestige V: 77 plays
+     * - Prestige VI: 115 plays
+     * - Prestige VII: 173 plays
+     * - Prestige VIII: 259 plays
+     * - Prestige IX: 389 plays
+     * - Prestige X: 584 plays
+     *
+     * @param prestigeLevel - The prestige level to get threshold for
+     * @returns Number of plays required to master
+     */
+    static getPlaysThreshold(prestigeLevel: PrestigeLevel): number;
+    /**
+     * Get the XP threshold for a given prestige level.
+     * Returns custom threshold if set, otherwise calculates using 1.5x scaling.
+     *
+     * Calculated values:
+     * - Prestige 0: 1,000 XP
+     * - Prestige I: 1,500 XP
+     * - Prestige II: 2,250 XP
+     * - Prestige III: 3,375 XP
+     * - Prestige IV: 5,063 XP
+     * - Prestige V: 7,594 XP
+     * - Prestige VI: 11,391 XP
+     * - Prestige VII: 17,086 XP
+     * - Prestige VIII: 25,629 XP
+     * - Prestige IX: 38,444 XP
+     * - Prestige X: 57,666 XP
+     *
+     * @param prestigeLevel - The prestige level to get threshold for
+     * @returns XP required to master
+     */
+    static getXPThreshold(prestigeLevel: PrestigeLevel): number;
+    /**
+     * Set custom thresholds for a specific prestige level.
+     * Pass null to use calculated value, omit to keep existing setting.
+     *
+     * @param prestigeLevel - The prestige level to customize
+     * @param thresholds - Custom threshold values (null = use calculated, omit = keep existing)
+     *
+     * @example
+     * ```typescript
+     * // Set both custom thresholds
+     * PrestigeSystem.setCustomThresholds(5, { playsThreshold: 100, xpThreshold: 10000 });
+     *
+     * // Set only plays threshold, keep XP calculated
+     * PrestigeSystem.setCustomThresholds(3, { playsThreshold: 50 });
+     *
+     * // Reset plays to calculated value
+     * PrestigeSystem.setCustomThresholds(3, { playsThreshold: null });
+     * ```
+     */
+    static setCustomThresholds(prestigeLevel: PrestigeLevel, thresholds: CustomThresholds): void;
+    /**
+     * Clear custom thresholds for a specific prestige level or all levels.
+     * After clearing, calculated defaults will be used.
+     *
+     * @param prestigeLevel - Optional prestige level to clear. If omitted, clears all.
+     *
+     * @example
+     * ```typescript
+     * // Clear custom thresholds for prestige level 5
+     * PrestigeSystem.clearCustomThresholds(5);
+     *
+     * // Clear all custom thresholds
+     * PrestigeSystem.clearCustomThresholds();
+     * ```
+     */
+    static clearCustomThresholds(prestigeLevel?: PrestigeLevel): void;
+    /**
+     * Check if custom thresholds are set for a prestige level.
+     *
+     * @param prestigeLevel - The prestige level to check
+     * @returns Whether custom thresholds exist for this level
+     */
+    static hasCustomThresholds(prestigeLevel: PrestigeLevel): boolean;
+    /**
+     * Get the current custom thresholds for a prestige level.
+     *
+     * @param prestigeLevel - The prestige level to get thresholds for
+     * @returns Custom thresholds or undefined if none set
+     */
+    static getCustomThresholds(prestigeLevel: PrestigeLevel): CustomThresholds | undefined;
+    /**
+     * Check if a track is mastered based on plays AND XP.
+     * Both thresholds must be met to be considered mastered.
+     *
+     * @param listenCount - Number of times the track has been listened to
+     * @param totalXP - Total XP earned from this track
+     * @param prestigeLevel - Current prestige level
+     * @returns True if BOTH thresholds are met
+     */
+    static isMastered(listenCount: number, totalXP: number, prestigeLevel: PrestigeLevel): boolean;
+    /**
+     * Check if a character can prestige (mastered AND not at max level).
+     *
+     * @param prestigeLevel - Current prestige level
+     * @param listenCount - Number of times the track has been listened to
+     * @param totalXP - Total XP earned from this track
+     * @returns True if character can prestige
+     */
+    static canPrestige(prestigeLevel: PrestigeLevel, listenCount: number, totalXP: number): boolean;
+    /**
+     * Determine if a track just reached mastery status in this session.
+     * Checks if the track went from not mastered to mastered between the two states.
+     *
+     * @param previousListenCount - Listen count before the current session
+     * @param currentListenCount - Listen count including the current session
+     * @param previousXP - Total XP before the current session
+     * @param currentXP - Total XP including the current session
+     * @param prestigeLevel - Current prestige level
+     * @returns True if mastery was achieved exactly in this session
+     */
+    static isJustMastered(previousListenCount: number, currentListenCount: number, previousXP: number, currentXP: number, prestigeLevel: PrestigeLevel): boolean;
+    /**
+     * Calculate the bonus XP awarded for achieving mastery.
+     *
+     * @param isMastered - Whether the track is mastered
+     * @returns Bonus XP amount if mastered, 0 otherwise
+     */
+    static calculateMasteryBonus(isMastered: boolean): number;
+    /**
+     * Get complete prestige information for UI display.
+     *
+     * @param prestigeLevel - Current prestige level
+     * @param listenCount - Number of times the track has been listened to
+     * @param totalXP - Total XP earned from this track
+     * @returns Complete PrestigeInfo object
+     */
+    static getPrestigeInfo(prestigeLevel: PrestigeLevel, listenCount: number, totalXP: number): PrestigeInfo;
+    /**
+     * Convert a prestige level to its Roman numeral representation.
+     *
+     * @param level - The prestige level
+     * @returns Roman numeral string (empty string for level 0)
+     */
+    static toRomanNumeral(level: PrestigeLevel): string;
+    /**
+     * Get the next prestige level after prestiging.
+     * Returns null if already at max level.
+     *
+     * @param currentLevel - Current prestige level
+     * @returns Next prestige level or null if at max
+     */
+    static getNextPrestigeLevel(currentLevel: PrestigeLevel): PrestigeLevel | null;
+    /**
+     * Create a PrestigeResult for a successful prestige operation.
+     *
+     * @param previousLevel - The prestige level before prestiging
+     * @param newLevel - The prestige level after prestiging
+     * @returns PrestigeResult object
+     */
+    static createSuccessResult(previousLevel: PrestigeLevel, newLevel: PrestigeLevel): PrestigeResult;
+    /**
+     * Create a PrestigeResult for a failed prestige operation.
+     *
+     * @param reason - The reason for failure
+     * @param currentLevel - The current prestige level
+     * @returns PrestigeResult object
+     */
+    static createFailureResult(reason: string, currentLevel: PrestigeLevel): PrestigeResult;
+    /**
+     * Get all threshold values for display/debugging purposes.
+     *
+     * @returns Array of { level, plays, xp } objects
+     */
+    static getAllThresholds(): Array<{
+        level: PrestigeLevel;
+        plays: number;
+        xp: number;
+    }>;
+}
+//# sourceMappingURL=PrestigeSystem.d.ts.map

package/dist/core/progression/PrestigeSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrestigeSystem.d.ts","sourceRoot":"","sources":["../../../src/core/progression/PrestigeSystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACH,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAOxB,MAAM,sBAAsB,CAAC;AAG9B;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IACvB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAmD;IAMlF;;;;;;;;;;;;;;;;;;;OAmBG;WACW,iBAAiB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM;IAQrE;;;;;;;;;;;;;;;;;;;OAmBG;WACW,cAAc,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM;IAYlE;;;;;;;;;;;;;;;;;;OAkBG;WACW,mBAAmB,CAC7B,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,gBAAgB,GAC7B,IAAI;IAIP;;;;;;;;;;;;;;OAcG;WACW,qBAAqB,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI;IAQxE;;;;;OAKG;WACW,mBAAmB,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO;IAIxE;;;;;OAKG;WACW,mBAAmB,CAAC,aAAa,EAAE,aAAa,GAAG,gBAAgB,GAAG,SAAS;IAQ7F;;;;;;;;OAQG;WACW,UAAU,CACpB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,GAC7B,OAAO;IAMV;;;;;;;OAOG;WACW,WAAW,CACrB,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GAChB,OAAO;IASV;;;;;;;;;;OAUG;WACW,cAAc,CACxB,mBAAmB,EAAE,MAAM,EAC3B,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,aAAa,GAC7B,OAAO;IAMV;;;;;OAKG;WACW,qBAAqB,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM;IAQhE;;;;;;;OAOG;WACW,eAAe,CACzB,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GAChB,YAAY;IAwBf;;;;;OAKG;WACW,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM;IAI1D;;;;;;OAMG;WACW,oBAAoB,CAAC,YAAY,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI;IAOrF;;;;;;OAMG;WACW,mBAAmB,CAC7B,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,aAAa,GACxB,cAAc;IAYjB;;;;;;OAMG;WACW,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,GAAG,cAAc;IAS9F;;;;OAIG;WACW,gBAAgB,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAY/F"}

package/dist/core/progression/RhythmXPCalculator.d.ts

@@ -0,0 +1,182 @@
+/**
+ * RhythmXPCalculator - Calculates XP for rhythm game button presses
+ *
+ * This calculator handles two parallel systems:
+ * 1. Per-button-press XP (this class) - rewards timing accuracy, combos, groove
+ * 2. Listening session XP boost (XPCalculator) - boosts background listening XP
+ *
+ * The system separates "score points" (for display/leaderboards) from
+ * "character XP" (for progression) via the `xpRatio` parameter.
+ */
+import type { BeatAccuracy } from '../types/BeatMap.js';
+import type { RhythmXPConfig, RhythmXPResult, ComboEndBonusResult, GrooveEndStats, GrooveEndBonusResult, RhythmSessionTotals } from '../types/RhythmXP.js';
+/**
+ * Calculates XP rewards for rhythm game button presses
+ *
+ * The RhythmXPCalculator can be used in two modes:
+ * 1. **Stateless**: Call `calculateButtonPressXP()` directly, frontend tracks combo/session
+ * 2. **Stateful**: Use `startSession()`, `recordHit()`, `getSessionTotals()`, `endSession()`
+ *
+ * @example Stateless usage
+ * ```typescript
+ * const calculator = new RhythmXPCalculator({ xpRatio: 0.1 });
+ * const result = calculator.calculateButtonPressXP(buttonResult, { comboLength: 50 });
+ * console.log(`Score: ${result.finalScore}, XP: ${result.finalXP}`);
+ * ```
+ *
+ * @example Stateful session tracking
+ * ```typescript
+ * const calculator = new RhythmXPCalculator();
+ * calculator.startSession();
+ *
+ * // On each hit
+ * const result = calculator.recordHit(buttonResult, { comboLength, grooveHotness });
+ *
+ * // Get running totals for UI
+ * const totals = calculator.getSessionTotals();
+ *
+ * // End session
+ * const finalTotals = calculator.endSession();
+ * ```
+ */
+export declare class RhythmXPCalculator {
+    private config;
+    private sessionTotals;
+    private sessionStartTime;
+    /**
+     * Create a new RhythmXPCalculator instance
+     *
+     * @param config - Optional partial configuration to override defaults
+     */
+    constructor(config?: Partial<RhythmXPConfig>);
+    /**
+     * Calculate XP for a single button press
+     *
+     * This is the main method for calculating XP rewards. It considers:
+     * - Base XP from accuracy level (via xpRatio conversion)
+     * - Combo multiplier (if enabled)
+     * - Groove multiplier (if per-hit groove is enabled)
+     *
+     * @param accuracy - The accuracy level of the hit
+     * @param options - Optional combo length and groove hotness
+     * @returns RhythmXPResult with score and XP values
+     */
+    calculateButtonPressXP(accuracy: BeatAccuracy, options?: {
+        comboLength?: number;
+        grooveHotness?: number;
+    }): RhythmXPResult;
+    /**
+     * Calculate combo end bonus
+     *
+     * Call this when a combo breaks (miss or wrongKey) to award a bonus
+     * based on the combo length achieved.
+     *
+     * @param comboLength - The combo length that just ended (before reset)
+     * @returns ComboEndBonusResult with bonus score and XP
+     */
+    calculateComboEndBonus(comboLength: number): ComboEndBonusResult;
+    /**
+     * Calculate groove end bonus
+     *
+     * Call this when a groove ends (hotness drops to 0 or session ends).
+     * Uses weighted calculation based on groove statistics.
+     *
+     * Note: Requires a minimum streak of 2 to award any bonus. Short grooves
+     * (maxStreak < 2) return 0 bonus to prevent excessive rewards for brief streaks.
+     *
+     * @param stats - Groove statistics from GrooveAnalyzer.getGrooveStats()
+     * @returns GrooveEndBonusResult with bonus score and XP
+     */
+    calculateGrooveEndBonus(stats: GrooveEndStats): GrooveEndBonusResult;
+    /**
+     * Get base score points for an accuracy level
+     *
+     * These are "score points" - raw values before xpRatio is applied.
+     *
+     * @param accuracy - The accuracy level
+     * @returns Base score points for this accuracy
+     */
+    getBaseXP(accuracy: BeatAccuracy): number;
+    /**
+     * Calculate combo multiplier from combo length
+     *
+     * Default formula: 1 + (comboLength / 50), capped at config.combo.cap
+     * At 50 combo = 2x, at 100 combo = 3x, at 200 combo = 5x (with default cap)
+     *
+     * @param comboLength - Current combo count
+     * @returns Multiplier value (capped at config.combo.cap)
+     */
+    getComboMultiplier(comboLength: number): number;
+    /**
+     * Default combo multiplier formula
+     *
+     * 1 + (comboLength / 25), capped at config.combo.cap
+     * - At 0 combo = 1x (no bonus)
+     * - At 25 combo = 2x
+     * - At 50 combo = 3x
+     * - At 100 combo = 5x (cap with default config)
+     */
+    private defaultComboFormula;
+    /**
+     * Start a new session
+     *
+     * Resets all totals and records the start time.
+     * Call this at the beginning of a rhythm game session.
+     */
+    startSession(): void;
+    /**
+     * Record a hit and update session totals
+     *
+     * Calculates XP for the hit AND updates internal session totals.
+     * This is a convenience method for stateful session tracking.
+     *
+     * @param accuracy - The accuracy level of the hit
+     * @param options - Optional combo length and groove hotness
+     * @returns RhythmXPResult with score and XP values
+     */
+    recordHit(accuracy: BeatAccuracy, options?: {
+        comboLength?: number;
+        grooveHotness?: number;
+    }): RhythmXPResult;
+    /**
+     * Get current session totals for UI display
+     *
+     * Returns a snapshot of the current session statistics.
+     *
+     * @returns RhythmSessionTotals or null if no session is active
+     */
+    getSessionTotals(): RhythmSessionTotals | null;
+    /**
+     * End session and get final totals
+     *
+     * Returns final session statistics and clears session state.
+     *
+     * @returns RhythmSessionTotals or null if no session was active
+     */
+    endSession(): RhythmSessionTotals | null;
+    /**
+     * Create empty session totals object
+     */
+    private createEmptyTotals;
+    /**
+     * Recalculate accuracy percentage
+     *
+     * Accuracy = (perfect + great + good + ok) / total hits
+     */
+    private recalculateAccuracyPercentage;
+    /**
+     * Get current configuration
+     *
+     * @returns Current RhythmXPConfig
+     */
+    getConfig(): RhythmXPConfig;
+    /**
+     * Update configuration
+     *
+     * Merges provided partial config with current configuration.
+     *
+     * @param config - Partial configuration to merge
+     */
+    updateConfig(config: Partial<RhythmXPConfig>): void;
+}
+//# sourceMappingURL=RhythmXPCalculator.d.ts.map

package/dist/core/progression/RhythmXPCalculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RhythmXPCalculator.d.ts","sourceRoot":"","sources":["../../../src/core/progression/RhythmXPCalculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACR,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAM9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,MAAM,CAAiB;IAG/B,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,gBAAgB,CAAuB;IAE/C;;;;OAIG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAQ5C;;;;;;;;;;;OAWG;IACH,sBAAsB,CAClB,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;KAC1B,GACF,cAAc;IAkDjB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB;IAuBhE;;;;;;;;;;;OAWG;IACH,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,oBAAoB;IAmCpE;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM;IAIzC;;;;;;;;OAQG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAc/C;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;OAKG;IACH,YAAY,IAAI,IAAI;IAKpB;;;;;;;;;OASG;IACH,SAAS,CACL,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;KAC1B,GACF,cAAc;IA2BjB;;;;;;OAMG;IACH,gBAAgB,IAAI,mBAAmB,GAAG,IAAI;IAY9C;;;;;;OAMG;IACH,UAAU,IAAI,mBAAmB,GAAG,IAAI;IAUxC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;;OAIG;IACH,OAAO,CAAC,6BAA6B;IAoBrC;;;;OAIG;IACH,SAAS,IAAI,cAAc;IAI3B;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;CAMtD"}