playlist-data-engine 1.1.0

package/dist/core/generation/CRLevelConverter.d.ts

@@ -0,0 +1,242 @@
+/**
+ * CR/Level Conversion Utilities
+ *
+ * Provides bidirectional conversion between Challenge Rating (CR) and character level
+ * for enemy generation and encounter balancing.
+ *
+ * These functions use D&D 5e-style mappings with smooth interpolation for fractional
+ * CR values and configurable tuning parameters for game balance adjustments.
+ */
+/**
+ * CR Tuning Configuration
+ *
+ * Controls how CR and level values are converted and scaled.
+ * Allows game balance adjustments without code changes.
+ */
+export interface CRTuningConfig {
+    /**
+     * Base multiplier for CR-to-level conversion
+     * Default: 1.0 (standard D&D 5e mapping)
+     * Higher values make enemies scale faster with CR
+     */
+    baseMultiplier: number;
+    /**
+     * Level offset applied after conversion
+     * Default: 0 (no offset)
+     * Can be used to shift all enemies to be slightly stronger/weaker
+     */
+    levelOffset: number;
+    /**
+     * Custom CR/level mappings that override the default calculation
+     * Key is CR, value is the exact level to use
+     */
+    customCurve: Map<number, number>;
+    /**
+     * Minimum level for any CR
+     * Prevents CR 0 from resulting in negative levels
+     */
+    minLevel: number;
+    /**
+     * Maximum level cap
+     * Default: Infinity (no cap — CR scales to any level)
+     * Set to a finite number to cap conversions (e.g., 20 for standard D&D 5e)
+     */
+    maxLevel: number;
+}
+/**
+ * Default CR tuning configuration
+ *
+ * Standard D&D 5e mapping: CR 0 = level 0, CR 1 = level 1, CR 2 = level 2, etc.
+ */
+export declare const DEFAULT_CR_TUNING: CRTuningConfig;
+/**
+ * Convert Challenge Rating to character level
+ *
+ * Uses D&D 5e-style mapping with smooth interpolation for fractional CRs.
+ *
+ * Default mapping (with baseMultiplier: 1.0, levelOffset: 0):
+ * - CR 0 = level 0
+ * - CR 0.125 (1/8) = level 0.125
+ * - CR 0.25 (1/4) = level 0.25
+ * - CR 0.5 (1/2) = level 0.5
+ * - CR 1 = level 1
+ * - CR 2 = level 2
+ * - CR 10 = level 10
+ * - CR 20 = level 20
+ * - CR 30 = level 30
+ * - CR 50 = level 50
+ * - No upper limit by default
+ *
+ * The formula is: level = (CR * baseMultiplier) + levelOffset
+ * Custom curve mappings take precedence over the calculated value.
+ *
+ * @param cr - Challenge Rating (supports decimals like 0.25, 0.5)
+ * @param tuning - Optional tuning configuration (defaults to DEFAULT_CR_TUNING)
+ * @returns Character level (may be fractional, typically rounded for use)
+ *
+ * @example
+ * ```typescript
+ * // Standard conversions
+ * crToLevel(0);     // 0
+ * crToLevel(0.25);  // 0.25
+ * crToLevel(0.5);   // 0.5
+ * crToLevel(1);     // 1
+ * crToLevel(5);     // 5
+ * crToLevel(10);    // 10
+ *
+ * // With custom tuning for harder enemies
+ * const hardMode = { ...DEFAULT_CR_TUNING, baseMultiplier: 1.2 };
+ * crToLevel(5, hardMode); // 6 (5 * 1.2)
+ *
+ * // With custom curve override
+ * const customCurve = new Map([[5, 7]]);
+ * const customTuning = { ...DEFAULT_CR_TUNING, customCurve };
+ * crToLevel(5, customTuning); // 7 (uses custom mapping)
+ * ```
+ */
+export declare function crToLevel(cr: number, tuning?: CRTuningConfig): number;
+/**
+ * Convert character level to Challenge Rating
+ *
+ * Inverse of crToLevel(). Uses the same tuning parameters to ensure
+ * bidirectional consistency.
+ *
+ * The formula is: CR = (level - levelOffset) / baseMultiplier
+ * Custom curve mappings are searched for a matching level first.
+ *
+ * @param level - Character level (supports decimals)
+ * @param tuning - Optional tuning configuration (defaults to DEFAULT_CR_TUNING)
+ * @returns Challenge Rating (may be fractional)
+ *
+ * @example
+ * ```typescript
+ * // Standard conversions
+ * levelToCR(0);     // 0
+ * levelToCR(1);     // 1
+ * levelToCR(5);     // 5
+ * levelToCR(10);    // 10
+ *
+ * // With custom tuning
+ * const hardMode = { ...DEFAULT_CR_TUNING, baseMultiplier: 1.2 };
+ * levelToCR(6, hardMode); // 5 (6 / 1.2)
+ *
+ * // Bidirectional consistency
+ * const original = 5;
+ * const converted = levelToCR(crToLevel(original)); // 5
+ * ```
+ */
+export declare function levelToCR(level: number, tuning?: CRTuningConfig): number;
+/**
+ * Round a level to the nearest valid character level
+ *
+ * D&D 5e levels are integers (1-20). This utility rounds fractional levels
+ * to the nearest integer, clamping to the valid range.
+ *
+ * Note: The default minLevel is 1 for standard D&D 5e characters.
+ * Pass 0 as minLevel if you want to allow level 0 results.
+ *
+ * @param level - Level value (may be fractional)
+ * @param minLevel - Minimum valid level (default: 1)
+ * @param maxLevel - Maximum valid level (default: Infinity — no cap)
+ * @returns Rounded integer level
+ *
+ * @example
+ * ```typescript
+ * roundLevel(0.5, 1, Infinity);   // 1
+ * roundLevel(1.2, 1, Infinity);   // 1
+ * roundLevel(2.7, 1, Infinity);   // 3
+ * roundLevel(25, 1, Infinity);    // 25
+ * roundLevel(50, 1, Infinity);    // 50
+ * roundLevel(0.4, 0, Infinity);   // 0 (minLevel 0 allows 0)
+ * ```
+ */
+export declare function roundLevel(level: number, minLevel?: number, maxLevel?: number): number;
+/**
+ * Round a CR to the nearest valid CR step
+ *
+ * D&D 5e CRs typically use specific fractional values: 0, 1/8, 1/4, 1/2, 1, 2, 3, etc.
+ * This utility rounds to the nearest valid CR step.
+ *
+ * Valid CR steps (1-30): 0, 0.125, 0.25, 0.5, 1, 2, 3, ..., 24, 26, 27, 28, 29, 30
+ * For CR > 30, falls back to the nearest integer (no step table).
+ * (CR 25 does not exist in standard D&D 5e)
+ *
+ * When equidistant between two steps, prefers the higher value (rounds up).
+ *
+ * @param cr - CR value (may be any decimal)
+ * @returns Rounded CR to nearest valid step
+ *
+ * @example
+ * ```typescript
+ * roundCR(0.1);   // 0.125 (closest to 1/8)
+ * roundCR(0.3);   // 0.25
+ * roundCR(1.5);   // 2 (equidistant, rounds up)
+ * roundCR(4.4);   // 4
+ * roundCR(50.3);  // 50 (above 30, uses integer rounding)
+ * ```
+ */
+export declare function roundCR(cr: number): number;
+/**
+ * Get level as a formatted string with fractional notation
+ *
+ * Converts decimal levels to D&D-style notation where applicable.
+ * For example, 0.25 becomes "0 (1/4)" for display purposes.
+ *
+ * @param level - Level value (may be fractional)
+ * @returns Formatted level string
+ *
+ * @example
+ * ```typescript
+ * formatLevel(0);     // "0"
+ * formatLevel(0.125); // "0 (1/8)"
+ * formatLevel(0.25);  // "0 (1/4)"
+ * formatLevel(0.5);   // "0 (1/2)"
+ * formatLevel(1);     // "1"
+ * formatLevel(5.5);   // "5.5"
+ * ```
+ */
+export declare function formatLevel(level: number): string;
+/**
+ * Get CR as a formatted string with fractional notation
+ *
+ * Converts decimal CRs to D&D-style notation.
+ * For example, 0.25 becomes "1/4" and 0.125 becomes "1/8".
+ *
+ * @param cr - CR value (may be fractional)
+ * @returns Formatted CR string
+ *
+ * @example
+ * ```typescript
+ * formatCR(0);     // "0"
+ * formatCR(0.125); // "1/8"
+ * formatCR(0.25);  // "1/4"
+ * formatCR(0.5);   // "1/2"
+ * formatCR(1);     // "1"
+ * formatCR(5);     // "5"
+ * ```
+ */
+export declare function formatCR(cr: number): string;
+/**
+ * Create a custom CR tuning configuration
+ *
+ * Factory function to create tuning configs with partial overrides.
+ * Merges provided options with defaults.
+ *
+ * @param options - Partial tuning options to override
+ * @returns Complete CRTuningConfig
+ *
+ * @example
+ * ```typescript
+ * // Harder enemies: CR converts to higher levels
+ * const hardMode = createCRTuning({ baseMultiplier: 1.2 });
+ *
+ * // Softer enemies: CR converts to lower levels
+ * const easyMode = createCRTuning({ baseMultiplier: 0.8 });
+ *
+ * // Custom curve for specific CRs
+ * const customCurve = new Map([[10, 12], [20, 25]]);
+ * const custom = createCRTuning({ customCurve });
+ * ```
+ */
+export declare function createCRTuning(options?: Partial<CRTuningConfig>): CRTuningConfig;
+//# sourceMappingURL=CRLevelConverter.d.ts.map

package/dist/core/generation/CRLevelConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CRLevelConverter.d.ts","sourceRoot":"","sources":["../../../src/core/generation/CRLevelConverter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAM/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAE,cAAkC,GAAG,MAAM,CAaxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,cAAkC,GAAG,MAAM,CAe3F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,EAAE,QAAQ,GAAE,MAAiB,GAAG,MAAM,CAGnG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CA8B1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBjD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAsB3C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,cAAc,CAMpF"}

package/dist/core/generation/CharacterGenerator.d.ts

@@ -0,0 +1,194 @@
+import type { CharacterSheet, Class, Race, GameMode } from '../types/Character.js';
+import type { AudioProfile } from '../types/AudioProfile.js';
+import type { PlaylistTrack } from '../types/Playlist.js';
+/**
+ * Extension data for custom spells
+ */
+export interface SpellExtension {
+    name: string;
+    level: number;
+    school: string;
+    casting_time?: string;
+    range?: string;
+    duration?: string;
+    components?: string[];
+    description?: string;
+}
+/**
+ * Extension data for custom equipment
+ */
+export interface EquipmentExtension {
+    name: string;
+    type: 'weapon' | 'armor' | 'item';
+    rarity: 'common' | 'uncommon' | 'rare' | 'very_rare' | 'legendary';
+    weight: number;
+}
+/**
+ * Extension data for custom races (race name only, uses existing Race enum)
+ */
+export type RaceExtension = string;
+/**
+ * Extension data for custom classes (class name only, uses existing Class enum)
+ */
+export type ClassExtension = string;
+/**
+ * Extension data for custom appearance options
+ */
+export type AppearanceExtension = {
+    bodyTypes?: string[];
+    skinTones?: string[];
+    hairColors?: string[];
+    hairStyles?: string[];
+    eyeColors?: string[];
+    facialFeatures?: string[];
+};
+/**
+ * Extension configuration for CharacterGenerator
+ */
+export interface CharacterGeneratorExtensions {
+    /** Custom spells to add */
+    spells?: SpellExtension[];
+    /** Custom equipment to add */
+    equipment?: EquipmentExtension[];
+    /** Custom races to add (race names) */
+    races?: RaceExtension[];
+    /** Custom classes to add (class names) */
+    classes?: ClassExtension[];
+    /** Custom appearance options */
+    appearance?: AppearanceExtension;
+}
+export interface CharacterGeneratorOptions {
+    /** Starting level (default: 1) */
+    level?: number;
+    /** Override class suggestion */
+    forceClass?: Class;
+    /** Override race selection (required when specifying a subrace other than 'pure') */
+    forceRace?: Race;
+    /** Game mode for stat progression (default: 'standard') */
+    gameMode?: GameMode;
+    /** Override automatic name generation with custom name */
+    forceName?: string;
+    /** Generate deterministic names (same seed = same name). Default: true */
+    deterministicName?: boolean;
+    /**
+     * Optional subrace selection
+     *
+     * - `'pure'` - Explicitly generate character with no subrace (no race required)
+     * - `undefined` - Randomly select between 'pure' and available subraces for the race
+     * - `'Specific Subrace'` - Manually specify a subrace (REQUIRES `forceRace` to also be set)
+     *
+     * @example
+     * // Random subrace or pure
+     * const randomSubrace = CharacterGenerator.generate(seed, audio, track);
+     *
+     * @example
+     * // Explicitly no subrace
+     * const pure = CharacterGenerator.generate(seed, audio, track, { subrace: 'pure' });
+     *
+     * @example
+     * // Specific subrace with race (both required)
+     * const highElf = CharacterGenerator.generate(seed, audio, track, { forceRace: 'Elf', subrace: 'High Elf' });
+     */
+    subrace?: string;
+    /**
+     * Custom extensions for procedural generation
+     * Allows adding custom spells, equipment, races, classes, and appearance options
+     */
+    extensions?: CharacterGeneratorExtensions;
+}
+/**
+ * Generate D&D 5e-compliant character sheets deterministically from audio signatures
+ *
+ * Uses seeded random number generation to ensure the same seed always produces
+ * the same character. Combines audio frequency analysis with blockchain metadata
+ * to create unique, reproducible characters.
+ */
+export declare class CharacterGenerator {
+    /**
+     * Register custom extensions with the ExtensionManager
+     *
+     * This method registers custom spells, equipment, races, classes, and appearance
+     * options that will be merged with the default data during character generation.
+     *
+     * @param extensions - Custom extensions to register
+     *
+     * @example
+     * CharacterGenerator.registerExtensions({
+     *     spells: [{ name: 'Phoenix Fire', level: 5, school: 'Evocation' }],
+     *     equipment: [{ name: 'Dragon Scale Armor', type: 'armor', rarity: 'rare', weight: 25 }],
+     *     races: ['Dragonborn'],
+     *     classes: ['Paladin'],
+     *     appearance: { bodyTypes: ['muscular'] }
+     * });
+     */
+    private static registerExtensions;
+    /**
+     * Generate a complete D&D 5e character sheet from audio profile and seed
+     *
+     * Deterministically generates:
+     * - Race (with racial ability bonuses)
+     * - Class (suggested by audio profile frequency analysis)
+     * - Ability scores (based on bass/mid/treble dominance)
+     * - Skills, proficiencies, and saving throws
+     * - Hit points and armor class
+     * - Character appearance (color-matched to audio)
+     *
+     * Same seed + audio profile = identical character every time.
+     *
+     * @param {string} seed - Deterministic seed (e.g., "chain-contract-tokenId")
+     * @param {AudioProfile} audioProfile - Audio frequency analysis results
+     * @param {PlaylistTrack} track - Track metadata (title, artist, genre) for automatic name generation
+     * @param {CharacterGeneratorOptions} [options] - Generation options
+     * @param {number} [options.level=1] - Starting level (1-20)
+     * @param {Class} [options.forceClass] - Override class suggestion
+     * @param {Race} [options.forceRace] - Override race selection (required when subrace is specified)
+     * @param {GameMode} [options.gameMode='standard'] - Game mode for stat progression
+     * @param {string} [options.subrace] - Subrace: 'pure' (no subrace), undefined (random), or specific subrace name
+     * @param {boolean} [options.deterministicName=true] - Generate deterministic names (same seed = same name)
+     * @param {CharacterGeneratorExtensions} [options.extensions] - Custom extensions
+     * @returns {CharacterSheet} Complete D&D 5e character sheet
+     *
+     * @example
+     * const character = CharacterGenerator.generate(
+     *   'polygon-0x123-456',
+     *   audioProfile,
+     *   track,
+     *   { level: 5 }
+     * );
+     * console.log(`${character.name}: Level ${character.level} ${character.class}`);
+     *
+     * @example
+     * // Explicitly no subrace
+     * const pure = CharacterGenerator.generate(
+     *   'seed',
+     *   audioProfile,
+     *   track,
+     *   { subrace: 'pure' }
+     * );
+     *
+     * @example
+     * // Specific subrace with race (both required)
+     * const highElf = CharacterGenerator.generate(
+     *   'seed',
+     *   audioProfile,
+     *   track,
+     *   { forceRace: 'Elf', subrace: 'High Elf' }
+     * );
+     *
+     * @example
+     * // With custom spells and non deterministic name
+     * const customCharacter = CharacterGenerator.generate(
+     *   'seed',
+     *   audioProfile,
+     *   track,
+     *   {
+     *     deterministicName: false,
+     *     extensions: {
+     *       spells: [{ name: 'Phoenix Fire', level: 5, school: 'Evocation' }]
+     *     }
+     *   }
+     * );
+     */
+    static generate(seed: string, audioProfile: AudioProfile, track: PlaylistTrack, options?: CharacterGeneratorOptions): CharacterSheet;
+}
+//# sourceMappingURL=CharacterGenerator.d.ts.map

package/dist/core/generation/CharacterGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CharacterGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/generation/CharacterGenerator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAW,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAmB1D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAClC,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IACnE,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IACzC,2BAA2B;IAC3B,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,8BAA8B;IAC9B,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACjC,uCAAuC;IACvC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,gCAAgC;IAChC,UAAU,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED,MAAM,WAAW,yBAAyB;IACtC,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,gCAAgC;IAChC,UAAU,CAAC,EAAE,KAAK,CAAC;IAEnB,qFAAqF;IACrF,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,4BAA4B,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC3B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAgDjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACH,MAAM,CAAC,QAAQ,CACX,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,yBAA8B,GACxC,cAAc;CAsRpB"}

package/dist/core/generation/ClassSuggester.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Class Suggester - Affinity-based class selection with baseline system
+ * Based on specs/001-core-engine/SPEC.md
+ */
+import type { Class } from '../types/Character.js';
+import type { AudioProfile } from '../types/AudioProfile.js';
+import { SeededRNG } from '../../utils/random.js';
+/**
+ * Suggest D&D 5e classes based on audio frequency analysis
+ *
+ * Key improvements over previous implementation:
+ * - **4% baseline probability**: All classes always have at least 4% chance
+ * - **Affinity-based selection**: Smooth affinity scoring instead of hard thresholds
+ * - **No class lockout**: Any class can be selected at any time
+ * - **Audio influences smoothly**: Higher affinity = higher probability (up to 50%+)
+ *
+ * Maps audio characteristics to character classes:
+ * - High bass (strength) → Barbarian, Fighter, Paladin
+ * - High treble (dexterity) → Rogue, Ranger, Monk
+ * - High mid (intelligence/wisdom) → Wizard, Cleric, Druid
+ * - High amplitude (charisma) → Bard, Sorcerer, Warlock
+ *
+ * Supports the extensibility system:
+ * - Custom classes can be registered via ExtensionManager
+ * - Spawn rates can be customized per class
+ * - Audio-based affinities are combined with custom spawn rate weights
+ */
+export declare class ClassSuggester {
+    /**
+     * Minimum probability for each class (4%)
+     *
+     * This ensures that even with unfavorable audio, every class has a chance.
+     * The remaining (1 - baseline × num_classes) is distributed by affinity.
+     */
+    private static readonly BASELINE_PROBABILITY;
+    /**
+     * Suggest a class based on audio frequency dominance
+     *
+     * Algorithm:
+     * 1. Calculate affinity for each class based on audio profile
+     * 2. Convert affinities to probabilities with 4% baseline
+     * 3. Apply custom spawn rate weights (custom takes priority)
+     * 4. Weighted random selection with seeded RNG
+     *
+     * The affinity system uses smooth scoring instead of hard thresholds:
+     * - Each class has preferred audio traits (bass, treble, mid, amplitude)
+     * - Primary trait contributes 100% of its weight
+     * - Secondary trait contributes 50% of its weight
+     * - Tertiary trait contributes 25% of its weight
+     * - Result: Smooth affinity score based on how close audio is to "ideal"
+     *
+     * The baseline system ensures variety:
+     * - Each class gets 4% minimum probability
+     * - Audio can boost a class from 4% to 50%+
+     * - No class ever has 0% chance
+     *
+     * @param {AudioProfile} audioProfile - Frequency analysis results (bass/mid/treble/amplitude)
+     * @param {SeededRNG} rng - Seeded random number generator for deterministic selection
+     * @returns {Class} Suggested D&D 5e class
+     *
+     * @example
+     * ```typescript
+     * const audioProfile = await analyzer.extractSonicFingerprint(audioUrl);
+     * const suggestedClass = ClassSuggester.suggest(audioProfile, rng);
+     * console.log(`This audio suggests: ${suggestedClass}`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With custom spawn weights
+     * const manager = ExtensionManager.getInstance();
+     * manager.setWeights('classes', { 'Barbarian': 2, 'Wizard': 0.5 });  // Make barbarians more common
+     * const suggestedClass = ClassSuggester.suggest(audioProfile, rng);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With custom classes
+     * manager.register('classes', ['Necromancer', 'Battlemage'], {
+     *     mode: 'relative',
+     *     weights: { 'Necromancer': 0.3, 'Battlemage': 0.5 }
+     * });
+     * const suggestedClass = ClassSuggester.suggest(audioProfile, rng);
+     * ```
+     */
+    static suggest(audioProfile: AudioProfile, rng: SeededRNG): Class;
+    /**
+     * Calculate affinity score for all classes based on audio profile
+     *
+     * Uses CLASS_AUDIO_PREFERENCES to determine how much each class "likes"
+     * the current audio profile. Higher affinity = higher probability.
+     *
+     * Affinity calculation:
+     * - Primary trait: audio_value × weight × 1.0
+     * - Secondary trait: audio_value × weight × 0.5
+     * - Tertiary trait: audio_value × weight × 0.25
+     * - Chaos: variance across all traits × 0.5
+     *
+     * @param {AudioProfile} audioProfile - Frequency analysis results
+     * @param {Class[]} allClasses - All available classes (default + custom)
+     * @returns {Record<Class, number>} Affinity scores for each class
+     * @private
+     */
+    private static calculateAllAffinities;
+    /**
+     * Calculate affinity score for a single class
+     *
+     * Checks for audio preferences in this order:
+     * 1. CLASS_AUDIO_PREFERENCES (for default D&D 5e classes)
+     * 2. ExtensionManager's classes.data (for custom classes with audio_preferences)
+     * 3. Returns neutral affinity (0.5) if no preferences found
+     *
+     * Audio preferences structure:
+     * - primary: Most important audio trait (bass/treble/mid/amplitude/chaos)
+     * - secondary: Optional secondary trait
+     * - tertiary: Optional tertiary trait
+     * - weights: Multipliers for each frequency band (0-1 range)
+     *
+     * Special trait: "chaos" rewards high variance across frequency bands
+     *
+     * @param {AudioProfile} audioProfile - Frequency analysis results
+     * @param {Class} characterClass - Class to calculate affinity for
+     * @returns {number} Affinity score (0-1+ range, can exceed 1 with boosts)
+     * @private
+     */
+    private static calculateClassAffinity;
+    /**
+     * Get audio preferences for a custom class from ExtensionManager
+     *
+     * Checks the 'classes.data' category for custom class entries that include
+     * audio_preferences. This allows custom classes to participate in affinity-based
+     * class suggestion.
+     *
+     * @param {Class} characterClass - Class to get audio preferences for
+     * @returns Audio preferences object or undefined if not found
+     * @private
+     */
+    private static getCustomClassAudioPreferences;
+    /**
+     * Get the contribution of a specific audio trait to affinity
+     *
+     * @param {AudioProfile} audioProfile - Frequency analysis results
+     * @param {AudioTrait} trait - The trait to get contribution for
+     * @param prefs - Class audio preferences with weights
+     * @param {number} multiplier - Contribution multiplier (1.0, 0.5, or 0.25)
+     * @returns {number} Trait contribution to affinity
+     * @private
+     */
+    private static getTraitContribution;
+    /**
+     * Convert affinity scores to probabilities with 4% baseline
+     *
+     * Algorithm:
+     * 1. Normalize affinities to 0-1 range
+     * 2. Apply 4% baseline to each class
+     * 3. Distribute remaining probability by normalized affinity
+     * 4. Renormalize to ensure sum = 1.0
+     *
+     * Result: Each class has minimum 4% probability, audio influences remaining 52%
+     * (for 12 classes: 12 × 4% = 48% baseline, 52% distributed by affinity)
+     *
+     * @param {Record<string, number>} affinities - Affinity scores for each class
+     * @returns {Record<string, number>} Probabilities (sum = 1.0)
+     * @private
+     */
+    private static calculateProbabilities;
+    /**
+     * Apply custom spawn rate weights to probabilities
+     *
+     * Custom weights from ExtensionManager take priority over audio-based probabilities.
+     * This allows users to override audio suggestions with their own preferences.
+     *
+     * If no custom weights exist, returns audio-based probabilities unchanged.
+     * If custom weights exist, they replace the audio-based probabilities.
+     *
+     * @param {Record<string, number>} probabilities - Audio-based probabilities
+     * @param {Record<string, number>} customWeights - Custom spawn rate weights
+     * @param {Class[]} allClasses - All available classes
+     * @returns {Record<string, number>} Final probabilities (sum = 1.0)
+     * @private
+     */
+    private static applyCustomWeights;
+}
+//# sourceMappingURL=ClassSuggester.d.ts.map

package/dist/core/generation/ClassSuggester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClassSuggester.d.ts","sourceRoot":"","sources":["../../../src/core/generation/ClassSuggester.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAUlD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACvB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,EAAE,SAAS,GAAG,KAAK;IAwBjE;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAarC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAwCrC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IA4B7C;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IA8BnC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAiDrC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;CA+CpC"}