playlist-data-engine 1.1.0

package/dist/core/spells/SpellQuery.d.ts

@@ -0,0 +1,194 @@
+/**
+ * SpellQuery
+ *
+ * Central query interface for all spells (default D&D 5e and custom).
+ * Provides spell lookup and categorization by level, school, and class.
+ *
+ * **Design:** This is a **query interface** around ExtensionManager.
+ * All spells are stored in ExtensionManager; SpellQuery provides:
+ * - Query methods with caching for performance
+ * - Spell-related helper methods
+ *
+ * No duplicate storage - all data lives in ExtensionManager.
+ *
+ * **Registration:** Use ExtensionManager.register('spells', [...]) to register spells.
+ */
+import type { Spell, SpellSchool } from './SpellTypes.js';
+import type { Class, CharacterSheet } from '../types/Character.js';
+import { type SpellValidationResult } from './SpellValidator.js';
+export type { SpellSchool };
+/**
+ * Extended Spell interface with optional query fields
+ */
+export interface RegisteredSpell extends Spell {
+    /** Unique identifier (uses name as ID if not provided) */
+    id: string;
+    /** Classes that can learn this spell */
+    classes?: Class[];
+    /** Source of the spell (default or custom) */
+    source?: 'default' | 'custom';
+}
+/**
+ * SpellQuery - Singleton class for querying spells
+ *
+ * This is a **query interface** around ExtensionManager.
+ * All spells are stored in ExtensionManager; SpellQuery provides:
+ * - Query methods with caching for performance
+ * - Spell-related helper methods
+ *
+ * Design principle: No duplicate storage. All data lives in ExtensionManager.
+ *
+ * **Registration:** Use ExtensionManager.register('spells', [...]) to register spells.
+ */
+export declare class SpellQuery {
+    private static instance;
+    private manager;
+    private allSpellsCache;
+    private levelCache;
+    private schoolCache;
+    private constructor();
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): SpellQuery;
+    /**
+     * Invalidate all caches
+     *
+     * This method is primarily for internal use and advanced scenarios.
+     *
+     * Call this after directly registering spells via ExtensionManager
+     * to ensure fresh data in query methods.
+     */
+    invalidateCache(): void;
+    /**
+     * Get a spell by ID
+     *
+     * @param spellId - Spell ID to look up
+     * @returns Spell or undefined if not found
+     */
+    getSpell(spellId: string): RegisteredSpell | undefined;
+    /**
+     * Get all registered spells
+     *
+     * Reads from ExtensionManager with caching.
+     *
+     * @returns Array of all spells
+     */
+    getSpells(): RegisteredSpell[];
+    /**
+     * Get spells by level
+     *
+     * Builds index from ExtensionManager data with caching.
+     *
+     * @param level - Spell level (0-9)
+     * @returns Array of spells at this level
+     */
+    getSpellsByLevel(level: number): RegisteredSpell[];
+    /**
+     * Get spells by school
+     *
+     * Builds index from ExtensionManager data with caching.
+     *
+     * @param school - Spell school to filter by
+     * @returns Array of spells from this school
+     */
+    getSpellsBySchool(school: SpellSchool): RegisteredSpell[];
+    /**
+     * Get spells available to a specific class
+     *
+     * Filters spells by their classes property.
+     *
+     * @param characterClass - Class to get spells for
+     * @returns Array of spells available to this class
+     */
+    getSpellsForClass(characterClass: Class): RegisteredSpell[];
+    /**
+     * Get spells available to a character (prerequisites met)
+     *
+     * Filters all spells by character prerequisites.
+     *
+     * @param character - Character sheet to validate against
+     * @returns Array of spells the character can learn
+     */
+    getAvailableSpells(character: CharacterSheet): RegisteredSpell[];
+    /**
+     * Get the spell list for a class (spell IDs)
+     *
+     * Reads from ExtensionManager.
+     *
+     * @param characterClass - Class to get spell list for
+     * @returns Array of spell IDs for this class
+     */
+    getClassSpellList(characterClass: Class): string[];
+    /**
+     * Get spell slots for a class at a specific level
+     *
+     * Note: This delegates to the getSpellSlotsForClass helper from constants.ts
+     * which handles both default and custom class spell slot progressions.
+     *
+     * @param characterClass - Class to get spell slots for
+     * @param level - Character level (1-20)
+     * @returns Number of spell slots at this level, or 0 if not a spellcaster
+     */
+    getSpellSlotsForClass(characterClass: Class, level: number): number;
+    /**
+     * Validate spell prerequisites against a character
+     *
+     * Checks if a character meets all prerequisite requirements for a spell.
+     * This is a convenience method that delegates to SpellValidator.
+     *
+     * @param spell - The spell whose prerequisites to validate
+     * @param character - The character sheet to validate against
+     * @returns Validation result with unmet prerequisites if any
+     */
+    validatePrerequisites(spell: RegisteredSpell, character: CharacterSheet): SpellValidationResult;
+    /**
+     * Validate spell data structure
+     *
+     * @param spell - Spell object to validate
+     * @returns Validation result with any errors
+     */
+    validateSpell(spell: RegisteredSpell): SpellValidationResult;
+    /**
+     * Check if a spell exists
+     *
+     * @param spellId - Spell ID to check
+     * @returns True if spell exists
+     */
+    hasSpell(spellId: string): boolean;
+    /**
+     * Get total spell count
+     *
+     * @returns Total number of registered spells
+     */
+    getSpellCount(): number;
+    /**
+     * Get spells by source
+     *
+     * @param source - 'default' or 'custom'
+     * @returns Array of spells from this source
+     */
+    getSpellsBySource(source: 'default' | 'custom'): RegisteredSpell[];
+    /**
+     * Get query statistics
+     *
+     * @returns Statistics about registered spells
+     */
+    getQueryStats(): {
+        totalSpells: number;
+        defaultSpells: number;
+        customSpells: number;
+        spellsByLevel: Record<number, number>;
+        spellsBySchool: Record<SpellSchool, number>;
+        classesWithSpells: number;
+    };
+}
+/**
+ * Get the global SpellQuery instance
+ *
+ * Convenience function for accessing the singleton.
+ *
+ * @returns SpellQuery instance
+ */
+export declare function getSpellQuery(): SpellQuery;
+//# sourceMappingURL=SpellQuery.d.ts.map

package/dist/core/spells/SpellQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpellQuery.d.ts","sourceRoot":"","sources":["../../../src/core/spells/SpellQuery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAKjF,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,KAAK;IAC1C,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;IAClB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAa;IACpC,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,WAAW,CAAoD;IAEvE,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,UAAU;IAOhC;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI;IAMvB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAKtD;;;;;;OAMG;IACH,SAAS,IAAI,eAAe,EAAE;IAQ9B;;;;;;;OAOG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE;IAclD;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,EAAE;IAczD;;;;;;;OAOG;IACH,iBAAiB,CAAC,cAAc,EAAE,KAAK,GAAG,eAAe,EAAE;IAO3D;;;;;;;OAOG;IACH,kBAAkB,CAAC,SAAS,EAAE,cAAc,GAAG,eAAe,EAAE;IAchE;;;;;;;OAOG;IACH,iBAAiB,CAAC,cAAc,EAAE,KAAK,GAAG,MAAM,EAAE;IAMlD;;;;;;;;;OASG;IACH,qBAAqB,CAAC,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAWnE;;;;;;;;;OASG;IACH,qBAAqB,CACjB,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,cAAc,GAC1B,qBAAqB;IAOxB;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,qBAAqB;IAI5D;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,eAAe,EAAE;IAIlE;;;;OAIG;IACH,aAAa,IAAI;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC5C,iBAAiB,EAAE,MAAM,CAAC;KAC7B;CA0CJ;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}

package/dist/core/spells/SpellTypes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Spell Types
+ *
+ * Type definitions for spell-related structures.
+ * Moved from src/utils/constants.ts for better module organization.
+ */
+import type { Class, Race } from '../types/Character.js';
+/**
+ * D&D 5e Schools of Magic
+ *
+ * The eight schools of magic categorize spells by their effects and methods.
+ * Used by the Spell interface and validation systems.
+ */
+export type SpellSchool = 'Abjuration' | 'Conjuration' | 'Divination' | 'Enchantment' | 'Evocation' | 'Illusion' | 'Necromancy' | 'Transmutation';
+/**
+ * Prerequisites for learning a spell
+ *
+ * Spells can require:
+ * - Level thresholds
+ * - Caster level thresholds
+ * - Ability score minimums
+ * - Specific class
+ * - Specific race
+ * - Specific features (by feature ID)
+ * - Specific spells (must be known first)
+ * - Specific skills (by proficiency)
+ * - Custom conditions
+ */
+export interface SpellPrerequisite {
+    /** Minimum character level */
+    level?: number;
+    /** Minimum spellcaster level (if different from character level) */
+    casterLevel?: number;
+    /** Minimum ability scores */
+    abilities?: Partial<Record<'STR' | 'DEX' | 'CON' | 'INT' | 'WIS' | 'CHA', number>>;
+    /** Specific class required */
+    class?: Class;
+    /** Specific race required */
+    race?: Race;
+    /** Features that must be learned first (by feature ID) */
+    features?: string[];
+    /** Spells that must be known first (by spell name) */
+    spells?: string[];
+    /** Skills that must be proficient first (by skill ID) */
+    skills?: string[];
+    /** Custom condition */
+    custom?: string;
+}
+/**
+ * Spell data structure
+ */
+export interface Spell {
+    /** Unique identifier (optional for backward compatibility) */
+    id?: string;
+    name: string;
+    level: number;
+    school: SpellSchool;
+    casting_time: string;
+    range: string;
+    components: string[];
+    duration: string;
+    /** Optional description of what the spell does */
+    description?: string;
+    /** Optional icon URL for small UI display */
+    icon?: string;
+    /** Optional image URL for larger display */
+    image?: string;
+    /** Prerequisites for learning this spell */
+    prerequisites?: SpellPrerequisite;
+}
+//# sourceMappingURL=SpellTypes.d.ts.map

package/dist/core/spells/SpellTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpellTypes.d.ts","sourceRoot":"","sources":["../../../src/core/spells/SpellTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,aAAa,GAAG,YAAY,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,eAAe,CAAC;AAElJ;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAC9B,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAEnF,8BAA8B;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd,6BAA6B;IAC7B,IAAI,CAAC,EAAE,IAAI,CAAC;IAEZ,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IAClB,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IAEjB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,4CAA4C;IAC5C,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACrC"}

package/dist/core/spells/SpellValidator.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Spell Validator
+ *
+ * Validates spells against strict schemas.
+ * Provides comprehensive validation for all spell properties including:
+ * - Required fields (name, level, school, casting_time, range, components, duration)
+ * - Valid enum values (school)
+ * - Level validation (0-9)
+ * - Optional fields (id, description, prerequisites)
+ * Uses shared AbilityConstants for code deduplication.
+ */
+import type { SpellPrerequisite, Spell } from './SpellTypes.js';
+import type { Ability, CharacterSheet } from '../types/Character.js';
+/**
+ * Validation result type
+ */
+export interface SpellValidationResult {
+    /** Whether the spell/prerequisite is valid */
+    valid: boolean;
+    /** Array of error messages (empty if valid) */
+    errors: string[];
+}
+/**
+ * SpellValidator - Validates spells and their prerequisites
+ *
+ * Provides strict validation to ensure spells
+ * meet all requirements and can validate prerequisites
+ * against a character sheet.
+ */
+export declare class SpellValidator {
+    /**
+     * Validate a spell
+     *
+     * Checks all required fields, enum values, and data constraints.
+     *
+     * @param spell - The spell to validate
+     * @returns Validation result with errors if any
+     */
+    static validateSpell(spell: unknown): SpellValidationResult;
+    /**
+     * Validate an array of spells
+     *
+     * @param spells - Array of spells to validate
+     * @returns Validation result with combined errors
+     */
+    static validateSpells(spells: unknown[]): SpellValidationResult;
+    /**
+     * Validate spell prerequisites schema
+     *
+     * Validates that the prerequisites object has valid structure.
+     * Uses the shared PrerequisiteValidator for consistency.
+     *
+     * @param prerequisites - The prerequisites to validate
+     * @returns Validation result with errors if any
+     */
+    static validatePrerequisites(prerequisites: unknown): SpellValidationResult;
+    /**
+     * Validate spell prerequisites against a character
+     *
+     * Checks if a character meets all prerequisite requirements for a spell.
+     * Uses the shared PrerequisiteValidator for consistency across all systems.
+     *
+     * @param prerequisites - The spell prerequisites to validate
+     * @param character - The character sheet to validate against
+     * @returns Validation result with unmet prerequisites if any
+     */
+    static validateSpellPrerequisites(prerequisites: SpellPrerequisite | undefined, character: CharacterSheet): SpellValidationResult;
+    /**
+     * Check if a string is a valid ability score
+     *
+     * Re-exports the shared isValidAbility function for convenience.
+     *
+     * @param ability - The ability string to check
+     * @returns True if it's a valid ability
+     */
+    static isValidAbility(ability: string): ability is Ability;
+    /**
+     * Check if a string is a valid spell school
+     *
+     * @param school - The school string to check
+     * @returns True if it's a valid school
+     */
+    static isValidSchool(school: string): school is Spell['school'];
+    /**
+     * Check if a number is a valid spell level
+     *
+     * @param level - The level to check
+     * @returns True if it's a valid spell level
+     */
+    static isValidSpellLevel(level: number): boolean;
+}
+/**
+ * Helper function to validate a single spell
+ *
+ * Convenience function for quick validation.
+ *
+ * @param spell - The spell to validate
+ * @returns Validation result with errors if any
+ */
+export declare function validateSpell(spell: unknown): SpellValidationResult;
+/**
+ * Helper function to validate an array of spells
+ *
+ * Convenience function for batch validation.
+ *
+ * @param spells - Array of spells to validate
+ * @returns Validation result with combined errors
+ */
+export declare function validateSpells(spells: unknown[]): SpellValidationResult;
+/**
+ * Helper function to validate spell prerequisites schema
+ *
+ * Convenience function for quick validation.
+ *
+ * @param prerequisites - The prerequisites to validate
+ * @returns Validation result with errors if any
+ */
+export declare function validateSpellPrerequisitesSchema(prerequisites: unknown): SpellValidationResult;
+/**
+ * Helper function to validate spell prerequisites against a character
+ *
+ * Convenience function for quick validation.
+ *
+ * @param prerequisites - The spell prerequisites to validate
+ * @param character - The character sheet to validate against
+ * @returns Validation result with unmet prerequisites if any
+ */
+export declare function validateSpellPrerequisites(prerequisites: SpellPrerequisite | undefined, character: CharacterSheet): SpellValidationResult;
+//# sourceMappingURL=SpellValidator.d.ts.map

package/dist/core/spells/SpellValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpellValidator.d.ts","sourceRoot":"","sources":["../../../src/core/spells/SpellValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA6BrE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC,8CAA8C;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB;IAiF3D;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,qBAAqB;IAuB/D;;;;;;;;OAQG;IACH,MAAM,CAAC,qBAAqB,CAAC,aAAa,EAAE,OAAO,GAAG,qBAAqB;IAI3E;;;;;;;;;OASG;IACH,MAAM,CAAC,0BAA0B,CAC7B,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,SAAS,EAAE,cAAc,GAC1B,qBAAqB;IAIxB;;;;;;;OAOG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,OAAO;IAI1D;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC;IAI/D;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGnD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAEnE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,qBAAqB,CAEvE;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,OAAO,GAAG,qBAAqB,CAE9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACtC,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,SAAS,EAAE,cAAc,GAC1B,qBAAqB,CAEvB"}

package/dist/core/spells/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Spells Module
+ *
+ * Provides spell validation, query, and prerequisite checking functionality.
+ */
+export { SpellValidator, validateSpell, validateSpells, validateSpellPrerequisitesSchema, validateSpellPrerequisites } from './SpellValidator.js';
+export { SpellQuery, getSpellQuery } from './SpellQuery.js';
+export type { SpellPrerequisite, Spell, SpellSchool } from './SpellTypes.js';
+export type { RegisteredSpell } from './SpellQuery.js';
+export type { SpellValidationResult } from './SpellValidator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/spells/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/spells/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,gCAAgC,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAClJ,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG5D,YAAY,EAAE,iBAAiB,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,143 @@
+/**
+ * Audio analysis type definitions
+ */
+export interface AudioProfile {
+    /** Bass dominance (0.0 - 1.0) */
+    bass_dominance: number;
+    /** Mid-range dominance (0.0 - 1.0) */
+    mid_dominance: number;
+    /** Treble dominance (0.0 - 1.0) */
+    treble_dominance: number;
+    /** Average amplitude (0.0 - 1.0) */
+    average_amplitude: number;
+    /** Advanced metrics (optional) */
+    spectral_centroid?: number;
+    spectral_rolloff?: number;
+    zero_crossing_rate?: number;
+    /** Color palette extracted from artwork (optional) */
+    color_palette?: ColorPalette;
+    /** Analysis metadata */
+    analysis_metadata: {
+        /** Duration of audio analyzed in seconds */
+        duration_analyzed: number;
+        /** Whether full buffer was analyzed (true for files < 3s) */
+        full_buffer_analyzed: boolean;
+        /** Sample positions used (percentages) */
+        sample_positions: number[];
+        /** Timestamp of analysis */
+        analyzed_at: string;
+    };
+    /** RMS (Root Mean Square) energy (0.0 - 1.0) */
+    rms_energy?: number;
+    /** Dynamic range (Peak - RMS) (0.0 - 1.0) */
+    dynamic_range?: number;
+}
+/**
+ * Event in a full timeline analysis
+ */
+export interface AudioTimelineEvent {
+    timestamp: number;
+    duration: number;
+    bass: number;
+    mid: number;
+    treble: number;
+    amplitude: number;
+    rms_energy: number;
+    peak: number;
+    dynamic_range: number;
+    spectral_centroid: number;
+    spectral_rolloff: number;
+    zero_crossing_rate: number;
+}
+export interface ColorPalette {
+    /** Dominant colors ranked by frequency (hex format) */
+    colors: string[];
+    /** Primary color (most dominant) */
+    primary_color: string;
+    /** Secondary color */
+    secondary_color?: string;
+    /** Accent color */
+    accent_color?: string;
+    /** Average brightness (0.0 - 1.0) */
+    brightness: number;
+    /** Average saturation (0.0 - 1.0) */
+    saturation: number;
+    /** Is the image monochrome? */
+    is_monochrome: boolean;
+}
+/**
+ * Frequency bands separated from audio analysis
+ *
+ * Rebalanced v2 ranges prevent treble dominance:
+ * - Bass: 20Hz - 400Hz (380 Hz range, 11% of spectrum)
+ * - Mid: 400Hz - 4kHz (3,600 Hz range, 52% of spectrum)
+ * - Treble: 4kHz - 14kHz (10,000 Hz range, 37% of spectrum)
+ *
+ * Previous v1 ranges (imbalanced):
+ * - Bass: 20Hz - 250Hz (only 3% of spectrum)
+ * - Mid: 250Hz - 4kHz (47% of spectrum)
+ * - Treble: 4kHz - 20kHz (200% of spectrum!)
+ */
+export interface FrequencyBands {
+    /** Bass frequencies (20Hz - 400Hz) */
+    bass: number[];
+    /** Mid frequencies (400Hz - 4kHz) */
+    mid: number[];
+    /** Treble frequencies (4kHz - 14kHz) */
+    treble: number[];
+}
+/**
+ * A detected classification tag (genre, mood, etc) with its confidence score
+ */
+export interface ClassificationTag {
+    /** The name of the tag (e.g. "rock", "happy", "party") */
+    name: string;
+    /** Confidence score from the ML model (0.0 to 1.0) */
+    confidence: number;
+}
+/**
+ * Vibe and engagement metrics extracted from audio
+ */
+export interface VibeMetrics {
+    /** Suitability for dancing (0.0 - 1.0) */
+    danceability?: number;
+    /** Perceived energy level (0.0 - 1.0) */
+    energy?: number;
+    /** Emotional positivity/happiness (0.0 - 1.0) */
+    valence?: number;
+    /** How "catchy" or engaging the track is (0.0 - 1.0) */
+    engagement?: number;
+    /** Likelihood of being acoustic vs electronic (0.0 - 1.0, >0.5 is more electronic) */
+    electronic_probability?: number;
+    /** Likelihood of being instrumental vs vocal (0.0 - 1.0, >0.5 is more instrumental) */
+    instrumental_probability?: number;
+}
+/**
+ * The output profile from the ML-based MusicClassifier
+ */
+export interface MusicClassificationProfile {
+    /** Top detected genres */
+    genres: ClassificationTag[];
+    /** Top detected moods and themes */
+    moods: ClassificationTag[];
+    /** Highest confidence genre */
+    primary_genre: string;
+    /** Semantic mood tags (highest confidence) */
+    mood_tags: string[];
+    /** High-level vibe metrics */
+    vibe_metrics?: VibeMetrics;
+    /** Analysis metadata */
+    analysis_metadata: {
+        /** ML models used in analysis */
+        models_used: string[];
+        /** Legacy: The primary model used (first in models_used) */
+        model_used?: string;
+        /** Legacy: Number of frames processed (usually 0) */
+        frames_analyzed?: number;
+        /** Duration of audio analyzed in seconds */
+        duration_analyzed: number;
+        /** Timestamp of analysis */
+        analyzed_at: string;
+    };
+}
+//# sourceMappingURL=AudioProfile.d.ts.map

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

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