playlist-data-engine 1.1.0

package/dist/core/types/Progression.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Progression and Environmental System Types
+ * Based on specs/001-core-engine/SPEC.md
+ */
+import type { CharacterSheet, Ability } from './Character.js';
+import type { EnvironmentalContext } from './Environmental.js';
+import type { RhythmGameContext } from './RhythmXP.js';
+export type { GeolocationData, MotionData, WeatherData, EnvironmentalContext } from './Environmental.js';
+/**
+ * GamingContext - Steam gaming activity data
+ * Game detection uses Steam API only.
+ */
+export interface GamingContext {
+    isActivelyGaming: boolean;
+    platformSource: 'steam' | 'none';
+    currentGame?: {
+        name: string;
+        source: 'steam';
+        genre?: string[];
+        sessionDuration?: number;
+        partySize?: number;
+    };
+    totalGamingMinutes: number;
+    gamesPlayedWhileListening: string[];
+    lastUpdated: number;
+}
+/**
+ * ListeningSession - Record of a single listening session
+ */
+export interface ListeningSession {
+    track_uuid: string;
+    start_time: number;
+    end_time: number;
+    duration_seconds: number;
+    base_xp_earned: number;
+    bonus_xp: number;
+    environmental_context?: EnvironmentalContext;
+    gaming_context?: GamingContext;
+    /** Rhythm game context for XP boost (System B) */
+    rhythm_game_context?: RhythmGameContext;
+    activity_type?: string;
+    total_xp_earned: number;
+}
+/**
+ * ExperienceSystem - Configuration for XP calculation
+ */
+export interface ExperienceSystem {
+    level_thresholds: number[];
+    xp_per_second: number;
+    xp_per_track_completion: number;
+    activity_bonuses: {
+        stationary: number;
+        walking: number;
+        running: number;
+        driving: number;
+        night_time: number;
+        extreme_weather: number;
+        high_altitude: number;
+        rhythm_game_base: number;
+        rhythm_game_combo: number;
+        rhythm_game_groove: number;
+    };
+    track_mastery_threshold: number;
+    mastery_bonus_xp: number;
+}
+/**
+ * Strategy selection - either a predefined type or custom implementation
+ */
+export type StatIncreaseStrategyType = 'dnD5e' | 'dnD5e_smart' | 'balanced' | 'primary_only' | 'random' | 'manual';
+/**
+ * Simple function type for custom stat increase formulas
+ * Game developers can provide a function instead of implementing the full interface
+ */
+export type StatIncreaseFunction = (character: CharacterSheet, increaseAmount: number, options?: StatIncreaseOptions) => Array<{
+    ability: Ability;
+    amount: number;
+}>;
+/**
+ * Options passed to strategy selection
+ */
+export interface StatIncreaseOptions {
+    /** Force specific abilities (overrides strategy logic) */
+    forcedAbilities?: Ability[];
+    /** Exclude certain abilities from selection */
+    excludedAbilities?: Ability[];
+    /** Require increasing multiple abilities (for +2, can be 2x+1 or 1x+2) */
+    requireMultiple?: boolean;
+    /** Prioritize these abilities (tiebreaker) */
+    priorityAbilities?: Ability[];
+}
+/**
+ * Base interface for stat increase strategies
+ */
+export interface StatIncreaseStrategy {
+    /** Strategy name for debugging/logging */
+    readonly name: string;
+    /**
+     * Determine which stats to increase
+     * @param character - Current character state
+     * @param increaseAmount - Total points to distribute (e.g., 2)
+     * @param options - Optional constraints
+     * @returns Array of {ability, amount} to increase
+     */
+    selectIncreases(character: CharacterSheet, increaseAmount: number, options?: StatIncreaseOptions): Array<{
+        ability: Ability;
+        amount: number;
+    }>;
+    /**
+     * Check if this strategy requires manual user input
+     * @param options - Optional constraints
+     * @returns true if strategy requires manual selection
+     */
+    requiresManualInput(options?: StatIncreaseOptions): boolean;
+}
+/**
+ * Stat increase configuration options
+ */
+export interface StatIncreaseConfig {
+    /** Maximum stat cap (default: 20 per D&D 5e, hard limit) */
+    maxStatCap: number;
+    /** Strategy to use for automatic stat increases on level up */
+    strategy: StatIncreaseStrategyType | StatIncreaseStrategy | StatIncreaseFunction;
+    /** When true, automatically apply stat increases during level up */
+    autoApply: boolean;
+    /** Custom stat increase levels (default: [4, 8, 12, 16, 19]) */
+    statIncreaseLevels: number[];
+}
+/**
+ * Stat increase result from any operation
+ */
+export interface StatIncreaseResult {
+    /** The character after modification */
+    character: CharacterSheet;
+    /** Stats that were increased */
+    increases: Array<{
+        ability: Ability;
+        oldValue: number;
+        newValue: number;
+        delta: number;
+    }>;
+    /** Stats that were NOT increased due to cap */
+    capped: Array<{
+        ability: Ability;
+        attemptedValue: number;
+        cappedAt: number;
+    }>;
+    /** Source of the increase */
+    source: 'level_up' | 'manual' | 'item' | 'event';
+    /** Timestamp of modification */
+    timestamp: number;
+}
+/**
+ * LevelUpDetail - Complete breakdown of what happened during a single level-up
+ */
+export interface LevelUpDetail {
+    /** Level before this level-up */
+    fromLevel: number;
+    /** Level after this level-up */
+    toLevel: number;
+    /** Hit points gained */
+    hpIncrease: number;
+    /** New max HP after level-up */
+    newMaxHP: number;
+    /** Proficiency bonus gained (0 if no increase) */
+    proficiencyIncrease: number;
+    /** New proficiency bonus after level-up */
+    newProficiency: number;
+    /** Stats that increased (if applicable) */
+    statIncreases?: Array<{
+        ability: Ability;
+        oldValue: number;
+        newValue: number;
+        delta: number;
+    }>;
+    /** Class features gained at this level */
+    featuresGained?: string[];
+    /**
+     * New spell slots after level-up (if spellcaster)
+     */
+    newSpellSlots?: Record<number, {
+        total: number;
+        used: number;
+    }>;
+}
+/**
+ * Result from applying a pending stat increase
+ */
+export interface ApplyPendingStatIncreaseResult {
+    /** Updated character with stats applied */
+    character: CharacterSheet;
+    /** Stats that were increased */
+    statIncreases: Array<{
+        ability: Ability;
+        oldValue: number;
+        newValue: number;
+        delta: number;
+    }>;
+    /** Remaining pending stat increases (counter) */
+    remainingPending: number;
+    /** Timestamp of completion */
+    timestamp: number;
+}
+/**
+ * Validation error for stat selection
+ */
+export interface StatSelectionValidationError {
+    /** Error message */
+    error: string;
+    /** What was wrong */
+    reason: 'invalid_ability' | 'invalid_amount' | 'exceeds_cap' | 'wrong_pattern' | 'duplicate_ability';
+    /** Valid patterns allowed */
+    allowedPatterns: string[];
+}
+//# sourceMappingURL=Progression.d.ts.map

package/dist/core/types/Progression.d.ts.map

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

package/dist/core/types/RhythmXP.d.ts

@@ -0,0 +1,398 @@
+/**
+ * Rhythm Game XP System Types
+ *
+ * This module defines types for the rhythm game XP reward system, which integrates
+ * with the existing beat detection and progression systems.
+ *
+ * The system separates "score points" (for in-game display/leaderboards) from
+ * "character XP" (for progression/leveling) via the `xpRatio` parameter.
+ *
+ * @example
+ * ```typescript
+ * // Default: 10 score points = 1 character XP
+ * const config: RhythmXPConfig = {
+ *   xpRatio: 0.1,
+ *   baseXP: { perfect: 10, great: 7, good: 5, ok: 2, miss: 0, wrongKey: 0 }
+ * };
+ * ```
+ */
+import type { BeatAccuracy } from './BeatMap.js';
+/**
+ * Base XP values for each accuracy level
+ *
+ * These are "score points" - raw values before the xpRatio is applied.
+ * Negative values for miss/wrongKey affect displayed score only;
+ * character XP is always floored at 0.
+ */
+export interface RhythmBaseXPConfig {
+    /** XP for perfect timing (default: 10) */
+    perfect: number;
+    /** XP for great timing (default: 7) */
+    great: number;
+    /** XP for good timing (default: 5) */
+    good: number;
+    /** XP for ok timing (default: 2) */
+    ok: number;
+    /** XP for missed beats (default: 0, can be negative for score penalty) */
+    miss: number;
+    /** XP for wrong key press (default: 0, can be negative for score penalty) */
+    wrongKey: number;
+}
+/**
+ * Combo end bonus configuration
+ *
+ * Awarded when a combo breaks, providing a satisfying "completion bonus"
+ * for the streak achieved.
+ */
+export interface ComboEndBonusConfig {
+    /** Whether combo end bonuses are enabled (default: true) */
+    enabled: boolean;
+    /**
+     * Custom formula for calculating bonus score from combo length.
+     * Default: (comboLength) => comboLength * 2
+     *
+     * @param comboLength - The combo length that just ended
+     * @returns Bonus score points (before xpRatio)
+     *
+     * @example
+     * ```typescript
+     * // Exponential bonus
+     * formula: (combo) => Math.floor(combo * 1.5)
+     *
+     * // Step-based (every 10 hits = bigger bonus)
+     * formula: (combo) => Math.floor(combo / 10) * 15
+     * ```
+     */
+    formula?: (comboLength: number) => number;
+}
+/**
+ * Combo multiplier configuration
+ *
+ * The combo multiplier increases with each successful hit and applies
+ * to the current hit only (not retroactively).
+ */
+export interface RhythmComboConfig {
+    /** Whether combo multipliers are enabled (default: true) */
+    enabled: boolean;
+    /** Maximum multiplier cap (default: 5.0, meaning 5x max) */
+    cap: number;
+    /**
+     * Custom formula for calculating multiplier from combo length.
+     * Default: (comboLength) => Math.min(1 + (comboLength / 50), cap)
+     *
+     * At 50 combo = 2x, at 100 combo = 3x, at 200 combo = 5x (cap)
+     *
+     * @param comboLength - Current combo count
+     * @returns Multiplier value (will be capped at `cap`)
+     *
+     * @example
+     * ```typescript
+     * // Uncapped exponential growth
+     * formula: (combo) => 1 + Math.log10(combo + 1)
+     *
+     * // Step-based (every 10 hits = +0.1x)
+     * formula: (combo) => 1 + Math.floor(combo / 10) * 0.1
+     * ```
+     */
+    formula?: (comboLength: number) => number;
+    /**
+     * Whether "ok" accuracy breaks the combo streak (default: true)
+     *
+     * When true: "ok" accuracy resets combo to 0 (stricter gameplay)
+     * When false: "ok" accuracy keeps the combo going (more forgiving)
+     *
+     * Note: This only affects combo streaks - the groove meter is NOT affected.
+     * "ok" accuracy still contributes positively to groove hotness.
+     *
+     * @example
+     * ```typescript
+     * // Default behavior - ok breaks combo
+     * okBreaksCombo: true
+     *
+     * // Forgiving mode - ok keeps combo alive
+     * okBreaksCombo: false
+     * ```
+     */
+    okBreaksCombo: boolean;
+    /** Combo end bonus configuration */
+    endBonus: ComboEndBonusConfig;
+}
+/**
+ * Groove end bonus configuration
+ *
+ * Awarded when a groove ends (hotness drops to 0 or session ends).
+ * The bonus is calculated using weighted values for different groove statistics.
+ */
+export interface GrooveEndBonusConfig {
+    /** Whether groove end bonuses are enabled (default: true) */
+    enabled: boolean;
+    /** Weight for max streak in bonus calculation (default: 0.4) */
+    maxStreakWeight: number;
+    /** Weight for average hotness in bonus calculation (default: 0.4) */
+    avgHotnessWeight: number;
+    /** Weight for groove duration in bonus calculation (default: 0.2) */
+    durationWeight: number;
+}
+/**
+ * Groove XP configuration
+ *
+ * Supports two modes:
+ * 1. Per-hit groove multiplier: Each hit gets bonus based on current hotness
+ * 2. End bonus: Large bonus awarded when groove ends (default)
+ */
+export interface RhythmGrooveConfig {
+    /**
+     * Whether to apply groove multiplier to each hit (default: false)
+     * When true: multiplier += (hotness / 100) * perHitScale
+     * At 100% hotness with scale 1.0 = +1.0x to multiplier
+     */
+    perHitMultiplier: boolean;
+    /**
+     * Scale factor for per-hit groove bonus (default: 1.0)
+     * Only used when perHitMultiplier is true
+     */
+    perHitScale: number;
+    /** End-of-groove bonus configuration */
+    endBonus: GrooveEndBonusConfig;
+}
+/**
+ * Complete rhythm XP configuration
+ *
+ * Controls how XP is calculated for rhythm game button presses.
+ * The system separates "score points" (for display) from "character XP" (for progression).
+ */
+export interface RhythmXPConfig {
+    /**
+     * Base XP values for each accuracy level.
+     * These are "score points" - raw values before xpRatio is applied.
+     */
+    baseXP: RhythmBaseXPConfig;
+    /**
+     * Score-to-XP conversion ratio.
+     * finalCharacterXP = scorePoints * xpRatio
+     *
+     * Examples:
+     * - xpRatio: 1.0  → 10 score = 10 XP (unchanged)
+     * - xpRatio: 0.1  → 10 score = 1 XP (default, tuned for D&D 5e progression)
+     * - xpRatio: 0.5  → 10 score = 5 XP (half)
+     *
+     * This allows tuning the rhythm game independently from character progression.
+     */
+    xpRatio: number;
+    /** Combo multiplier configuration */
+    combo: RhythmComboConfig;
+    /** Groove XP configuration */
+    groove: RhythmGrooveConfig;
+    /**
+     * Maximum total multiplier cap (default: 5.0)
+     * Applied after combining combo and groove multipliers
+     */
+    maxMultiplier: number;
+}
+/**
+ * Result of calculating XP for a single button press
+ *
+ * Contains both score (for display/leaderboards) and XP (for character progression).
+ */
+export interface RhythmXPResult {
+    /** Raw score from accuracy (before ratio and multipliers) */
+    scorePoints: number;
+    /** Score converted to XP base (scorePoints * xpRatio) */
+    baseXP: number;
+    /** Current combo multiplier applied */
+    comboMultiplier: number;
+    /** Groove bonus multiplier (0 if not enabled) */
+    grooveMultiplier: number;
+    /** Combined multiplier (capped at maxMultiplier) */
+    totalMultiplier: number;
+    /** Final score for display/leaderboards (scorePoints * totalMultiplier) */
+    finalScore: number;
+    /** Final character XP to add (baseXP * totalMultiplier, floored at 0) */
+    finalXP: number;
+    /** Breakdown of calculation inputs */
+    breakdown: {
+        /** Accuracy level of the hit */
+        accuracy: BeatAccuracy;
+        /** Combo length at time of hit */
+        comboLength: number;
+        /** Groove hotness at time of hit (0-100), if groove is active */
+        grooveHotness?: number;
+    };
+}
+/**
+ * Result of calculating combo end bonus
+ *
+ * Awarded when a combo breaks (miss or wrongKey after a streak).
+ */
+export interface ComboEndBonusResult {
+    /** The combo length that just ended */
+    comboLength: number;
+    /** Raw bonus score (before ratio) */
+    bonusScore: number;
+    /** Actual XP to add (bonusScore * xpRatio) */
+    bonusXP: number;
+}
+/**
+ * Statistics for groove end bonus calculation
+ *
+ * Retrieved from GrooveAnalyzer.getGrooveStats() when a groove ends.
+ */
+export interface GrooveStats {
+    /** Peak streak during groove */
+    maxStreak: number;
+    /** Peak hotness reached during groove */
+    maxHotness: number;
+    /** Average hotness over groove lifetime */
+    avgHotness: number;
+    /** How long groove lasted in seconds */
+    duration: number;
+    /** Total hits in groove */
+    totalHits: number;
+    /** When groove started (audio time) */
+    startTime: number;
+    /** When groove ended (audio time) */
+    endTime: number;
+}
+/**
+ * Statistics for groove end bonus calculation (simplified input)
+ *
+ * Used when calling calculateGrooveEndBonus() directly.
+ */
+export interface GrooveEndStats {
+    /** Peak streak during groove */
+    maxStreak: number;
+    /** Average hotness over groove lifetime */
+    avgHotness: number;
+    /** How long groove lasted in seconds */
+    duration: number;
+    /** Total hits in groove */
+    totalHits: number;
+}
+/**
+ * Result of calculating groove end bonus
+ *
+ * Awarded when a groove ends (hotness drops to 0 or session ends).
+ */
+export interface GrooveEndBonusResult {
+    /** Raw bonus score (before ratio) */
+    bonusScore: number;
+    /** Actual XP to add (bonusScore * xpRatio) */
+    bonusXP: number;
+}
+/**
+ * Cumulative session statistics for UI display
+ *
+ * Tracks totals over a rhythm game session for displaying
+ * session summaries without requiring frontend tracking.
+ */
+export interface RhythmSessionTotals {
+    /** Total raw score accumulated */
+    totalScore: number;
+    /** Total character XP earned */
+    totalXP: number;
+    /** Peak combo achieved */
+    maxCombo: number;
+    /** Count of each accuracy type */
+    accuracyDistribution: {
+        perfect: number;
+        great: number;
+        good: number;
+        ok: number;
+        miss: number;
+        wrongKey: number;
+    };
+    /** Overall accuracy percentage (perfect+great+good+ok / total hits) */
+    accuracyPercentage: number;
+    /** Session duration in seconds */
+    duration: number;
+}
+/**
+ * Rhythm game context for listening session XP boost
+ *
+ * When active, boosts the background listening XP while playing rhythm game.
+ * This is separate from the per-button-press XP (RhythmXPCalculator).
+ */
+export interface RhythmGameContext {
+    /** Is rhythm game mode currently active? */
+    isActive: boolean;
+    /** Current combo length */
+    currentCombo: number;
+    /** Max combo for scaling (default: 100) */
+    maxComboCap: number;
+    /** Current groove hotness (0-100) */
+    grooveHotness: number;
+    /** Average hotness over session (optional) */
+    avgGrooveHotness?: number;
+}
+/**
+ * Default rhythm XP configuration
+ *
+ * Tuned for D&D 5e progression with xpRatio: 0.1 (10 score points = 1 character XP).
+ *
+ * Note: The default combo multiplier formula (1 + comboLength/50, capped at 5.0) is
+ * implemented in RhythmXPCalculator. The config.combo.formula is only for custom formulas.
+ */
+export declare const DEFAULT_RHYTHM_XP_CONFIG: RhythmXPConfig;
+/**
+ * Merge user config with defaults
+ *
+ * Creates a complete RhythmXPConfig by merging user-provided partial
+ * configuration with sensible defaults.
+ *
+ * @param userConfig - Partial configuration to override defaults
+ * @returns Complete configuration
+ *
+ * @example
+ * ```typescript
+ * // Use all defaults
+ * const config = mergeRhythmXPConfig();
+ *
+ * // Customize XP ratio only
+ * const config = mergeRhythmXPConfig({ xpRatio: 0.2 });
+ *
+ * // Customize combo settings
+ * const config = mergeRhythmXPConfig({
+ *   combo: {
+ *     cap: 10.0,
+ *     formula: (combo) => 1 + Math.log10(combo + 1)
+ *   }
+ * });
+ * ```
+ */
+export declare function mergeRhythmXPConfig(userConfig?: Partial<RhythmXPConfig>): RhythmXPConfig;
+/**
+ * Determine if an accuracy level should break the combo streak.
+ *
+ * This helper function centralizes the combo-breaking logic so frontends
+ * don't have to duplicate it. It considers both the accuracy level and
+ * the `okBreaksCombo` configuration option.
+ *
+ * @param accuracy - The accuracy level of the hit
+ * @param okBreaksCombo - Whether "ok" accuracy breaks combo (default: true from config)
+ * @returns true if the accuracy should break the combo, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { shouldAccuracyBreakCombo, RhythmXPCalculator } from 'playlist-data-engine';
+ *
+ * const rhythmXP = new RhythmXPCalculator();
+ * const config = rhythmXP.getConfig();
+ *
+ * // Check if accuracy breaks combo
+ * if (shouldAccuracyBreakCombo(buttonResult.accuracy, config.combo.okBreaksCombo)) {
+ *   // Combo breaks - award end bonus before resetting
+ *   const bonus = rhythmXP.calculateComboEndBonus(currentCombo);
+ *   updater.addXP(character, bonus.bonusXP, 'combo_bonus');
+ *   currentCombo = 0;
+ * } else {
+ *   currentCombo++;
+ * }
+ *
+ * // Using with custom okBreaksCombo setting
+ * const customConfig = { combo: { okBreaksCombo: false } };
+ * const rhythmXP = new RhythmXPCalculator(customConfig);
+ * // Now "ok" accuracy will NOT break combo
+ * ```
+ */
+export declare function shouldAccuracyBreakCombo(accuracy: BeatAccuracy, okBreaksCombo?: boolean): boolean;
+//# sourceMappingURL=RhythmXP.d.ts.map

package/dist/core/types/RhythmXP.d.ts.map

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

package/dist/core/utils/AbilityConstants.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared Ability Constants
+ *
+ * Central location for ability-related constants and utility functions.
+ * Eliminates duplicate code across SkillValidator, SpellValidator, and FeatureValidator.
+ */
+import type { Ability } from '../types/Character.js';
+/**
+ * Valid D&D 5e abilities
+ *
+ * This constant is shared across:
+ * - SkillValidator (src/core/skills/SkillValidator.ts)
+ * - SpellValidator (src/core/spells/SpellValidator.ts)
+ * - FeatureValidator (src/core/features/FeatureValidator.ts)
+ */
+export declare const VALID_ABILITIES: ReadonlyArray<string>;
+/**
+ * Check if a string is a valid ability score
+ *
+ * This utility function is shared across validators to provide
+ * consistent ability validation throughout the codebase.
+ *
+ * @param ability - The ability string to check
+ * @returns True if it's a valid ability score
+ */
+export declare function isValidAbility(ability: string): ability is Ability;
+/**
+ * Alias for isValidAbility - both names are equivalent and supported
+ */
+export { isValidAbility as isAbility };
+//# sourceMappingURL=AbilityConstants.d.ts.map

package/dist/core/utils/AbilityConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbilityConstants.d.ts","sourceRoot":"","sources":["../../../src/core/utils/AbilityConstants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,MAAM,CAAuD,CAAC;AAE1G;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,OAAO,CAElE;AAED;;GAEG;AACH,OAAO,EAAE,cAAc,IAAI,SAAS,EAAE,CAAC"}