playlist-data-engine 1.1.0

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

@@ -0,0 +1,169 @@
+/**
+ * SessionTracker - Manages listening sessions with timestamps and XP calculation
+ * Based on specs/001-core-engine/SPEC.md
+ */
+import type { ListeningSession, EnvironmentalContext, GamingContext } from '../types/Progression.js';
+import type { PlaylistTrack } from '../types/Playlist.js';
+import type { ISessionTracker } from '../types/ISessionTracker.js';
+import { XPCalculator } from './XPCalculator.js';
+/**
+ * ActiveSession tracks a currently-playing listening session
+ */
+interface ActiveSession {
+    track_uuid: string;
+    start_time: number;
+    track?: PlaylistTrack;
+    environmental_context?: EnvironmentalContext;
+    gaming_context?: GamingContext;
+}
+/**
+ * SessionTracker class - Records and manages listening sessions
+ * Tracks active sessions and calculates XP earned
+ * Implements ISessionTracker for dependency injection flexibility
+ */
+export declare class SessionTracker implements ISessionTracker {
+    private activeSessions;
+    private sessionHistory;
+    private xpCalculator;
+    private sessionCounter;
+    /**
+     * Create a new SessionTracker
+     * @param xpCalculator - Optional custom XPCalculator instance
+     */
+    constructor(xpCalculator?: XPCalculator);
+    /**
+     * Start a new listening session
+     * @param trackUuid - UUID of the track being listened to
+     * @param track - Optional PlaylistTrack object for metadata
+     * @param context - Optional environmental and gaming context
+     * @returns Session ID for tracking
+     */
+    startSession(trackUuid: string, track?: PlaylistTrack, context?: {
+        environmental_context?: EnvironmentalContext;
+        gaming_context?: GamingContext;
+    }): string;
+    /**
+     * End a listening session and record it
+     * @param sessionId - The session ID returned from startSession
+     * @param durationOverride - Optional override for session duration (in seconds)
+     * @param activityType - Optional activity type (stationary, walking, running, driving)
+     * @returns The completed ListeningSession or null if session not found
+     */
+    endSession(sessionId: string, durationOverride?: number, activityType?: string): ListeningSession | null;
+    /**
+     * Get an active session without ending it
+     * Useful for tracking real-time progress
+     * @param sessionId - The session ID
+     * @returns The active session or null
+     */
+    getActiveSession(sessionId: string): ActiveSession | null;
+    /**
+     * Get duration of active session in seconds
+     * @param sessionId - The session ID
+     * @returns Duration in seconds or null if session not found
+     */
+    getActiveSessionDuration(sessionId: string): number | null;
+    /**
+     * Update context for an active session
+     * @param sessionId - The session ID
+     * @param context - New context data
+     * @returns True if updated, false if session not found
+     */
+    updateSessionContext(sessionId: string, context: {
+        environmental_context?: EnvironmentalContext;
+        gaming_context?: GamingContext;
+    }): boolean;
+    /**
+     * Get all recorded sessions
+     * @returns Array of all completed listening sessions
+     */
+    getSessionHistory(): ListeningSession[];
+    /**
+     * Get sessions for a specific track
+     * @param trackUuid - The track UUID to filter by
+     * @returns Array of sessions for that track
+     */
+    getSessionsForTrack(trackUuid: string): ListeningSession[];
+    /**
+     * Get total listening time across all sessions
+     * @returns Total time in seconds
+     */
+    getTotalListeningTime(): number;
+    /**
+     * Get total XP earned across all sessions
+     * @returns Total XP
+     */
+    getTotalXPEarned(): number;
+    /**
+     * Get total listening time for a specific track
+     * @param trackUuid - The track UUID
+     * @returns Total time in seconds for that track
+     */
+    getTrackListeningTime(trackUuid: string): number;
+    /**
+     * Get listen count for a track (number of sessions)
+     * @param trackUuid - The track UUID
+     * @returns Number of times the track has been listened to
+     */
+    getTrackListenCount(trackUuid: string): number;
+    /**
+     * Check if a track has been mastered
+     * @param trackUuid - The track UUID
+     * @param masteryThreshold - Minimum listen count to master (default 10)
+     * @returns True if track is mastered
+     */
+    isTrackMastered(trackUuid: string, masteryThreshold?: number): boolean;
+    /**
+     * Get sessions within a time range
+     * @param startTime - Start timestamp (Unix ms)
+     * @param endTime - End timestamp (Unix ms)
+     * @returns Array of sessions within the range
+     */
+    getSessionsInRange(startTime: number, endTime: number): ListeningSession[];
+    /**
+     * Get average session length
+     * @returns Average duration in seconds
+     */
+    getAverageSessionLength(): number;
+    /**
+     * Get the longest session
+     * @returns ListeningSession with longest duration or null
+     */
+    getLongestSession(): ListeningSession | null;
+    /**
+     * Get total XP earned for a specific track.
+     * Used by the prestige system to calculate track-level XP.
+     * @param trackUuid - The track UUID
+     * @returns Total XP earned from sessions for this track
+     */
+    getTrackXPTotal(trackUuid: string): number;
+    /**
+     * Clear all sessions for a specific track.
+     * Used by the prestige system to reset track progress after prestiging.
+     * @param trackUuid - The track UUID to clear sessions for
+     * @returns Number of sessions that were removed
+     */
+    clearTrackSessions(trackUuid: string): number;
+    /**
+     * Clear all session history
+     * Useful for testing or resetting
+     */
+    clearHistory(): void;
+    /**
+     * Clear active sessions
+     * Use with caution - active sessions will be lost
+     */
+    clearActiveSessions(): void;
+    /**
+     * Get count of active sessions
+     * @returns Number of currently active sessions
+     */
+    getActiveSessionCount(): number;
+    /**
+     * Get all active session IDs
+     * @returns Array of active session IDs
+     */
+    getActiveSessionIds(): string[];
+}
+export {};
+//# sourceMappingURL=SessionTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionTracker.d.ts","sourceRoot":"","sources":["../../../src/core/progression/SessionTracker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACR,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,UAAU,aAAa;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,qBAAqB,CAAC,EAAE,oBAAoB,CAAC;IAC7C,cAAc,CAAC,EAAE,aAAa,CAAC;CAClC;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,eAAe;IAClD,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAa;IAEnC;;;OAGG;gBACS,YAAY,CAAC,EAAE,YAAY;IAIvC;;;;;;OAMG;IACH,YAAY,CACR,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE;QACN,qBAAqB,CAAC,EAAE,oBAAoB,CAAC;QAC7C,cAAc,CAAC,EAAE,aAAa,CAAC;KAClC,GACF,MAAM;IAeT;;;;;;OAMG;IACH,UAAU,CACN,SAAS,EAAE,MAAM,EACjB,gBAAgB,CAAC,EAAE,MAAM,EACzB,YAAY,CAAC,EAAE,MAAM,GACtB,gBAAgB,GAAG,IAAI;IA2C1B;;;;;OAKG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAIzD;;;;OAIG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAM1D;;;;;OAKG;IACH,oBAAoB,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;QACL,qBAAqB,CAAC,EAAE,oBAAoB,CAAC;QAC7C,cAAc,CAAC,EAAE,aAAa,CAAC;KAClC,GACF,OAAO;IAcV;;;OAGG;IACH,iBAAiB,IAAI,gBAAgB,EAAE;IAIvC;;;;OAIG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAI1D;;;OAGG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;;OAGG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAOhD;;;;OAIG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAI9C;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAE,MAAW,GAAG,OAAO;IAI1E;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAM1E;;;OAGG;IACH,uBAAuB,IAAI,MAAM;IAKjC;;;OAGG;IACH,iBAAiB,IAAI,gBAAgB,GAAG,IAAI;IAO5C;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAO1C;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQ7C;;;OAGG;IACH,YAAY,IAAI,IAAI;IAIpB;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IAI3B;;;OAGG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;;OAGG;IACH,mBAAmB,IAAI,MAAM,EAAE;CAGlC"}

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

@@ -0,0 +1,128 @@
+/**
+ * XPCalculator - Handles all XP calculations for listening sessions
+ * Based on specs/001-core-engine/SPEC.md
+ */
+import type { ListeningSession, EnvironmentalContext, GamingContext } from '../types/Progression.js';
+import type { RhythmGameContext } from '../types/RhythmXP.js';
+import type { PlaylistTrack } from '../types/Playlist.js';
+import type { ExperienceSystem } from '../types/Progression.js';
+/**
+ * XPCalculator class - Manages experience point calculations
+ * with support for activity, environmental, and gaming bonuses
+ */
+export declare class XPCalculator {
+    private config;
+    /**
+     * Create a new XPCalculator
+     * @param options - Configuration options for XP calculation
+     */
+    constructor(options?: Partial<ExperienceSystem>);
+    /**
+     * Calculate total XP earned for a listening session
+     * Applies all multipliers: base, activity, environmental, gaming, rhythm game
+     *
+     * @param session - The listening session
+     * @param track - The playlist track (for duration validation)
+     * @returns Total XP earned after all bonuses
+     */
+    calculateSessionXP(session: ListeningSession, track?: PlaylistTrack): number;
+    /**
+     * Apply environmental bonuses to XP
+     * Accounts for time of day, weather, altitude, biome
+     *
+     * @param baseXP - Base XP value
+     * @param context - Environmental context data
+     * @returns XP with environmental bonuses applied
+     */
+    private applyEnvironmentalBonus;
+    /**
+     * Apply gaming bonuses to XP
+     * Rewards users who listen while gaming
+     *
+     * @param baseXP - Base XP value
+     * @param context - Gaming context data
+     * @returns XP with gaming bonuses applied
+     */
+    private applyGamingBonus;
+    /**
+     * Apply rhythm game bonuses to XP
+     * Rewards users who play rhythm game while listening (System B)
+     *
+     * @param baseXP - Base XP value
+     * @param context - Rhythm game context data
+     * @returns XP with rhythm game bonuses applied
+     */
+    private applyRhythmGameBonus;
+    /**
+     * Calculate total XP modifier (environmental + gaming combined)
+     * Capped at 3.0x to prevent excessive stacking
+     *
+     * @param envContext - Environmental context (optional)
+     * @param gamingContext - Gaming context (optional)
+     * @param rhythmGameContext - Rhythm game context (optional)
+     * @returns Combined multiplier (1.0 to 3.0)
+     */
+    calculateTotalModifier(envContext?: EnvironmentalContext, gamingContext?: GamingContext, rhythmGameContext?: RhythmGameContext): number;
+    /**
+     * Calculate environmental XP modifier
+     *
+     * @param context - Environmental context
+     * @returns Multiplier (1.0 to 3.0)
+     */
+    private calculateEnvironmentalModifier;
+    /**
+     * Calculate gaming XP modifier
+     *
+     * @param context - Gaming context
+     * @returns Multiplier (1.0 to 1.75)
+     */
+    private calculateGamingModifier;
+    /**
+     * Calculate rhythm game XP modifier (System B)
+     *
+     * @param context - Rhythm game context
+     * @returns Multiplier (1.0 to 2.25)
+     */
+    private calculateRhythmGameModifier;
+    /**
+     * Get the XP threshold for a specific level
+     *
+     * @param level - The level (1-20)
+     * @returns Total XP required to reach that level
+     */
+    getXPThresholdForLevel(level: number): number;
+    /**
+     * Get the XP required to advance from current level to next
+     *
+     * @param currentLevel - Current level (1-19)
+     * @returns XP needed to reach next level
+     */
+    getXPToNextLevel(currentLevel: number): number;
+    /**
+     * Determine what level a character should be at with given XP total
+     *
+     * @param totalXP - Total experience points
+     * @returns Character level (1-20)
+     */
+    getLevelFromXP(totalXP: number): number;
+    /**
+     * Check if track is mastered based on listen count
+     *
+     * @param listenCount - Number of times the track has been listened to
+     * @returns True if listen count meets or exceeds mastery threshold
+     */
+    isTrackMastered(listenCount: number): boolean;
+    /**
+     * Get the mastery bonus XP
+     *
+     * @returns XP bonus for mastering a track
+     */
+    getMasteryBonusXP(): number;
+    /**
+     * Get current configuration
+     *
+     * @returns The ExperienceSystem configuration
+     */
+    getConfig(): ExperienceSystem;
+}
+//# sourceMappingURL=XPCalculator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"XPCalculator.d.ts","sourceRoot":"","sources":["../../../src/core/progression/XPCalculator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACrG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AA8ChE;;;GAGG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAmB;IAEjC;;;OAGG;gBACS,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAc/C;;;;;;;OAOG;IACH,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM;IAoC5E;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IA2CxB;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;;;;;;OAQG;IACH,sBAAsB,CAClB,UAAU,CAAC,EAAE,oBAAoB,EACjC,aAAa,CAAC,EAAE,aAAa,EAC7B,iBAAiB,CAAC,EAAE,iBAAiB,GACtC,MAAM;IAsBT;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAqBtC;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAkC/B;;;;;OAKG;IACH,OAAO,CAAC,2BAA2B;IAmBnC;;;;;OAKG;IACH,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAO7C;;;;;OAKG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAS9C;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IASvC;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;OAIG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;;;OAIG;IACH,SAAS,IAAI,gBAAgB;CAGhC"}

package/dist/core/progression/stat/StatIncreaseStrategy.d.ts

@@ -0,0 +1,97 @@
+/**
+ * StatIncreaseStrategy - Built-in implementations for stat increase selection
+ *
+ * Provides multiple strategies for determining which stats to increase on level up:
+ * - DnD5eStandardStrategy: Manual selection (D&D 5e default)
+ * - DnD5eSmartStrategy: Intelligent auto-selection
+ * - BalancedStrategy: Always balances lowest stats
+ * - PrimaryOnlyStrategy: Always boosts class primary
+ * - RandomStrategy: Random selection
+ * - ManualStrategy: Requires explicit input
+ * - Function support: Accepts simple functions
+ */
+import type { CharacterSheet, Ability } from '../../types/Character.js';
+import type { StatIncreaseStrategy, StatIncreaseOptions, StatIncreaseStrategyType, StatIncreaseFunction } from '../../types/Progression.js';
+/**
+ * D&D 5e Standard Strategy
+ * Returns empty array requiring manual selection (D&D 5e default behavior)
+ */
+export declare class DnD5eStandardStrategy implements StatIncreaseStrategy {
+    readonly name = "D&D 5e Standard";
+    selectIncreases(character: CharacterSheet, increaseAmount: number, options?: StatIncreaseOptions): Array<{
+        ability: Ability;
+        amount: number;
+    }>;
+    requiresManualInput(options?: StatIncreaseOptions): boolean;
+}
+/**
+ * D&D 5e Smart Strategy
+ * Intelligently selects based on class and current stats
+ */
+export declare class DnD5eSmartStrategy implements StatIncreaseStrategy {
+    readonly name = "D&D 5e Smart";
+    selectIncreases(character: CharacterSheet, increaseAmount: number, options?: StatIncreaseOptions): Array<{
+        ability: Ability;
+        amount: number;
+    }>;
+    requiresManualInput(): boolean;
+    private shouldSplit;
+    private findLowestStat;
+}
+/**
+ * Balanced Strategy
+ * Always increases the two lowest stats by +1 each (or distributes evenly)
+ */
+export declare class BalancedStrategy implements StatIncreaseStrategy {
+    readonly name = "Balanced";
+    selectIncreases(character: CharacterSheet, increaseAmount: number, options?: StatIncreaseOptions): Array<{
+        ability: Ability;
+        amount: number;
+    }>;
+    requiresManualInput(): boolean;
+}
+/**
+ * Primary Only Strategy
+ * Always boosts the class's primary ability
+ */
+export declare class PrimaryOnlyStrategy implements StatIncreaseStrategy {
+    readonly name = "Primary Only";
+    selectIncreases(character: CharacterSheet, increaseAmount: number, options?: StatIncreaseOptions): Array<{
+        ability: Ability;
+        amount: number;
+    }>;
+    requiresManualInput(): boolean;
+    private findLowestStat;
+}
+/**
+ * Random Strategy
+ * Randomly selects abilities
+ */
+export declare class RandomStrategy implements StatIncreaseStrategy {
+    readonly name = "Random";
+    selectIncreases(character: CharacterSheet, increaseAmount: number, options?: StatIncreaseOptions): Array<{
+        ability: Ability;
+        amount: number;
+    }>;
+    requiresManualInput(): boolean;
+}
+/**
+ * Manual Strategy
+ * Always defers to manual stat selection
+ * Returns empty array to signal that manual input is required
+ * Stats should be applied via CharacterUpdater.applyPendingStatIncrease()
+ */
+export declare class ManualStrategy implements StatIncreaseStrategy {
+    readonly name = "Manual";
+    selectIncreases(_character: CharacterSheet, _increaseAmount: number, _options?: StatIncreaseOptions): Array<{
+        ability: Ability;
+        amount: number;
+    }>;
+    requiresManualInput(): boolean;
+}
+/**
+ * Factory function to create strategy instances
+ * Accepts either a string type, a full strategy implementation, or a simple function
+ */
+export declare function createStatIncreaseStrategy(strategy: StatIncreaseStrategyType | StatIncreaseStrategy | StatIncreaseFunction): StatIncreaseStrategy;
+//# sourceMappingURL=StatIncreaseStrategy.d.ts.map

package/dist/core/progression/stat/StatIncreaseStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatIncreaseStrategy.d.ts","sourceRoot":"","sources":["../../../../src/core/progression/stat/StatIncreaseStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACR,cAAc,EACd,OAAO,EAEV,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACR,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACvB,MAAM,4BAA4B,CAAC;AAGpC;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,oBAAoB;IAC9D,QAAQ,CAAC,IAAI,qBAAqB;IAElC,eAAe,CACX,SAAS,EAAE,cAAc,EACzB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAqB9C,mBAAmB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO;CAI9D;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,oBAAoB;IAC3D,QAAQ,CAAC,IAAI,kBAAkB;IAE/B,eAAe,CACX,SAAS,EAAE,cAAc,EACzB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAmD9C,mBAAmB,IAAI,OAAO;IAI9B,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;CAmBzB;AAED;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,oBAAoB;IACzD,QAAQ,CAAC,IAAI,cAAc;IAE3B,eAAe,CACX,SAAS,EAAE,cAAc,EACzB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA+B9C,mBAAmB,IAAI,OAAO;CAGjC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAC5D,QAAQ,CAAC,IAAI,kBAAkB;IAE/B,eAAe,CACX,SAAS,EAAE,cAAc,EACzB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAoB9C,mBAAmB,IAAI,OAAO;IAI9B,OAAO,CAAC,cAAc;CAsBzB;AAED;;;GAGG;AACH,qBAAa,cAAe,YAAW,oBAAoB;IACvD,QAAQ,CAAC,IAAI,YAAY;IAEzB,eAAe,CACX,SAAS,EAAE,cAAc,EACzB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAoB9C,mBAAmB,IAAI,OAAO;CAGjC;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,oBAAoB;IACvD,QAAQ,CAAC,IAAI,YAAY;IAEzB,eAAe,CACX,UAAU,EAAE,cAAc,EAC1B,eAAe,EAAE,MAAM,EACvB,QAAQ,CAAC,EAAE,mBAAmB,GAC/B,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAM9C,mBAAmB,IAAI,OAAO;CAGjC;AA4BD;;;GAGG;AACH,wBAAgB,0BAA0B,CACtC,QAAQ,EAAE,wBAAwB,GAAG,oBAAoB,GAAG,oBAAoB,GACjF,oBAAoB,CA6BtB"}

package/dist/core/progression/stat/StatManager.d.ts

@@ -0,0 +1,179 @@
+/**
+ * StatManager - Public API for all stat modifications
+ *
+ * This is the SINGLE SOURCE OF TRUTH for stat changes.
+ * All stat modifications MUST go through this class.
+ *
+ * Provides methods for:
+ * - Manual stat increases (potions, items, events)
+ * - Manual stat decreases (curses, poison)
+ * - Absolute stat setting
+ * - Level-up stat increases
+ */
+import type { CharacterSheet, Ability } from '../../types/Character.js';
+import type { StatIncreaseConfig, StatIncreaseResult, StatIncreaseOptions, StatSelectionValidationError } from '../../types/Progression.js';
+/**
+ * StatManager - Public API for stat modifications
+ *
+ * @example
+ * ```typescript
+ * // Create with default config (D&D 5e standard)
+ * const statManager = new StatManager();
+ *
+ * // Manual stat increase (potion)
+ * const result = statManager.increaseStats(
+ *   character,
+ *   [{ ability: 'STR', amount: 4 }],
+ *   'item'
+ * );
+ *
+ * // Process level up
+ * const levelUpResult = statManager.processLevelUp(character, 4, {
+ *   forcedAbilities: ['STR']
+ * });
+ * ```
+ */
+export declare class StatManager {
+    private config;
+    private strategy;
+    constructor(config?: Partial<StatIncreaseConfig>);
+    /**
+     * Increase stats manually (e.g., from potions, items, events)
+     *
+     * @param character - The character to modify
+     * @param increases - Array of {ability, amount} to increase
+     * @param source - Source of the increase (for tracking)
+     * @returns Result with updated character and change details
+     *
+     * @example
+     * ```typescript
+     * // Potion of Strength: +4 STR
+     * const result = statManager.increaseStats(character, [
+     *   { ability: 'STR', amount: 4 }
+     * ], 'item');
+     *
+     * if (result.capped.length > 0) {
+     *   console.log('Stat was capped at 20!');
+     * }
+     *
+     * const updatedCharacter = result.character;
+     * ```
+     */
+    increaseStats(character: CharacterSheet, increases: Array<{
+        ability: Ability;
+        amount: number;
+    }>, source?: StatIncreaseResult['source']): StatIncreaseResult;
+    /**
+     * Decrease stats (e.g., from curses, damage, poison)
+     *
+     * @param character - The character to modify
+     * @param decreases - Array of {ability, amount} to decrease
+     * @param source - Source of the decrease
+     * @returns Result with updated character and change details
+     *
+     * @example
+     * ```typescript
+     * // Curse lowering strength
+     * const result = statManager.decreaseStats(character, [
+     *   { ability: 'STR', amount: 2 }
+     * ], 'event');
+     * ```
+     */
+    decreaseStats(character: CharacterSheet, decreases: Array<{
+        ability: Ability;
+        amount: number;
+    }>, source?: StatIncreaseResult['source']): StatIncreaseResult;
+    /**
+     * Set a stat to a specific value (absolute, not relative)
+     *
+     * @param character - The character to modify
+     * @param ability - The ability to set
+     * @param value - The new value
+     * @param source - Source of the change
+     * @returns Result with updated character
+     *
+     * @example
+     * ```typescript
+     * // Set strength to 18
+     * const result = statManager.setStat(character, 'STR', 18, 'manual');
+     * ```
+     */
+    setStat(character: CharacterSheet, ability: Ability, value: number, source?: StatIncreaseResult['source']): StatIncreaseResult;
+    /**
+     * Process stat increases for level up
+     * This is called internally by LevelUpProcessor
+     *
+     * @param character - The character leveling up
+     * @param newLevel - The level being reached
+     * @param options - Optional overrides for this level up
+     * @returns Result with stat increases, or null if no increase at this level
+     */
+    processLevelUp(character: CharacterSheet, newLevel: number, options?: StatIncreaseOptions): StatIncreaseResult | null;
+    /**
+     * Update the configuration
+     *
+     * @param config - New config (partial)
+     *
+     * @example
+     * ```typescript
+     * // Change strategy mid-game
+     * statManager.updateConfig({
+     *   strategy: 'dnD5e_smart'
+     * });
+     *
+     * // Override stat cap (e.g., for epic mode)
+     * statManager.updateConfig({
+     *   maxStatCap: 30
+     * });
+     * ```
+     */
+    updateConfig(config: Partial<StatIncreaseConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<Required<StatIncreaseConfig>>;
+    /**
+     * Check if an ability can be increased
+     *
+     * @param character - The character to check
+     * @param ability - The ability to check
+     * @param amount - How much to increase by
+     * @returns true if increase is possible
+     *
+     * @example
+     * ```typescript
+     * if (statManager.canIncrease(character, 'STR', 2)) {
+     *   // Safe to increase
+     * }
+     * ```
+     */
+    canIncrease(character: CharacterSheet, ability: Ability, amount?: number): boolean;
+    /**
+     * Get stat cap for an ability
+     * @param character - The character to check (for game mode)
+     * @param ability - The ability to check
+     * @returns Stat cap for this character's game mode
+     */
+    getStatCap(character: CharacterSheet, _ability: Ability): number;
+    /**
+     * Validate stat selection follows D&D 5e rules
+     * Rules: +2 to one ability OR +1 to two abilities
+     *
+     * @param character - Character to validate against
+     * @param selections - User's stat selections
+     * @param increaseAmount - Total points to distribute (usually 2)
+     * @returns Validation result
+     */
+    validateDnD5eStatSelection(character: CharacterSheet, selections: Array<{
+        ability: Ability;
+        amount: number;
+    }>, increaseAmount?: number): {
+        valid: true;
+    } | StatSelectionValidationError;
+    /**
+     * Merge user config with defaults
+     * Note: Stat cap and increase levels are determined at runtime based on character's game mode
+     */
+    private mergeWithDefaults;
+}
+//# sourceMappingURL=StatManager.d.ts.map

package/dist/core/progression/stat/StatManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatManager.d.ts","sourceRoot":"","sources":["../../../../src/core/progression/stat/StatManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAY,MAAM,0BAA0B,CAAC;AAClF,OAAO,KAAK,EACR,kBAAkB,EAClB,kBAAkB,EAElB,mBAAmB,EAGnB,4BAA4B,EAC/B,MAAM,4BAA4B,CAAC;AAkBpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,QAAQ,CAAuB;gBAE3B,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAKhD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,aAAa,CACT,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EACtD,MAAM,GAAE,kBAAkB,CAAC,QAAQ,CAAY,GAChD,kBAAkB;IAmDrB;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CACT,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EACtD,MAAM,GAAE,kBAAkB,CAAC,QAAQ,CAAW,GAC/C,kBAAkB;IASrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACH,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,kBAAkB,CAAC,QAAQ,CAAY,GAChD,kBAAkB;IAOrB;;;;;;;;OAQG;IACH,cAAc,CACV,SAAS,EAAE,cAAc,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,kBAAkB,GAAG,IAAI;IAiC5B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI;IAUvD;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAInD;;;;;;;;;;;;;;OAcG;IACH,WAAW,CACP,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,MAAU,GACnB,OAAO;IASV;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM;IAKhE;;;;;;;;OAQG;IACI,0BAA0B,CAC7B,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EACvD,cAAc,GAAE,MAAU,GAC3B;QAAE,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG,4BAA4B;IA2EjD;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAU5B"}