playlist-data-engine 1.1.0

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

@@ -0,0 +1,397 @@
+/**
+ * D&D 5e Character type definitions
+ */
+import type { FeatureEffect } from '../features/FeatureTypes.js';
+import type { EquipmentProperty, EquipmentFeature, EquipmentSkill, EquipmentSpell, EnhancedInventoryItem } from './Equipment.js';
+import type { PrestigeLevel } from './Prestige.js';
+import type { StatLevelOverrides } from './Enemy.js';
+/**
+ * Branded type for extensible Race names
+ *
+ * This allows custom races to be registered via ExtensionManager while maintaining
+ * type safety. Use asRace() to convert a string to the Race type, and isValidRace()
+ * to validate at runtime.
+ *
+ * @example
+ * // Default D&D 5e races
+ * const defaultRace: Race = asRace('Human');
+ *
+ * // Custom race (must be registered via ExtensionManager first)
+ * const customRace: Race = asRace('Dragonkin');
+ * if (isValidRace(customRace)) {
+ *   // Safe to use
+ * }
+ *
+ * // Type augmentation alternative (for user projects):
+ * // declare module 'playlist-data-engine' {
+ * //   type Race = 'Human' | 'Elf' | ... | 'Tiefling' | 'Dragonkin';
+ * // }
+ */
+export type Race = string & {
+    readonly __RaceBrand: unique symbol;
+};
+/**
+ * Cast a string to the Race type
+ *
+ * This function performs a type assertion to convert any string to the Race type.
+ * Use isValidRace() first if you need runtime validation.
+ *
+ * @param value - The race name string
+ * @returns The value cast to Race type
+ *
+ * @example
+ * const raceName = 'Dragonkin';
+ * if (isValidRace(raceName)) {
+ *   const race: Race = asRace(raceName);
+ * }
+ */
+export declare function asRace(value: string): Race;
+/**
+ * Default D&D 5e races (pre-branded Race type values)
+ *
+ * These are the core races that are always available without needing ExtensionManager.
+ * Custom races can be added via ExtensionManager.register('races.data', [...]).
+ */
+export declare const DEFAULT_RACES: readonly Race[];
+/**
+ * Type guard to check if a string is a valid Race (default or custom)
+ *
+ * This checks against both default D&D 5e races and any custom races
+ * registered via ExtensionManager's 'races.data' category.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid race name
+ *
+ * @example
+ * if (isValidRace('Dragonkin')) {
+ *   // Safe to use as Race type
+ *   const race: Race = asRace('Dragonkin');
+ * }
+ */
+export declare function isValidRace(value: unknown): value is Race;
+/**
+ * Branded type for extensible Class names
+ *
+ * This allows custom classes to be registered via ExtensionManager while maintaining
+ * type safety. Use asClass() to convert a string to the Class type, and isValidClass()
+ * to validate at runtime.
+ *
+ * @example
+ * // Default D&D 5e classes
+ * const defaultClass: Class = 'Wizard' as Class;
+ *
+ * // Custom class (must be registered via ExtensionManager first)
+ * const customClass: Class = asClass('Necromancer');
+ * if (isValidClass(customClass)) {
+ *   // Safe to use
+ * }
+ *
+ * // Type augmentation alternative (for user projects):
+ * // declare module 'playlist-data-engine' {
+ * //   type Class = 'Barbarian' | ... | 'Wizard' | 'Necromancer';
+ * // }
+ */
+export type Class = string & {
+    readonly __ClassBrand: unique symbol;
+};
+/**
+ * Cast a string to the Class type
+ *
+ * This function performs a type assertion to convert any string to the Class type.
+ * Use isValidClass() first if you need runtime validation.
+ *
+ * @param value - The class name string
+ * @returns The value cast to Class type
+ *
+ * @example
+ * const className = 'Necromancer';
+ * if (isValidClass(className)) {
+ *   const cls: Class = asClass(className);
+ * }
+ */
+export declare function asClass(value: string): Class;
+/**
+ * Default D&D 5e classes (pre-branded Class type values)
+ *
+ * These are the core classes that are always available without needing ExtensionManager.
+ * Custom classes can be added via ExtensionManager.register('classes.data', [...]).
+ */
+export declare const DEFAULT_CLASSES: readonly Class[];
+/**
+ * Type guard to check if a string is a valid Class (default or custom)
+ *
+ * This checks against both default D&D 5e classes and any custom classes
+ * registered via ExtensionManager's 'classes.data' category.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid class name
+ *
+ * @example
+ * if (isValidClass('Necromancer')) {
+ *   // Safe to use as Class type
+ *   const cls: Class = 'Necromancer';
+ * }
+ */
+export declare function isValidClass(value: unknown): value is Class;
+export type Ability = 'STR' | 'DEX' | 'CON' | 'INT' | 'WIS' | 'CHA';
+export type Skill = 'athletics' | 'acrobatics' | 'sleight_of_hand' | 'stealth' | 'arcana' | 'history' | 'investigation' | 'nature' | 'religion' | 'animal_handling' | 'insight' | 'medicine' | 'perception' | 'survival' | 'deception' | 'intimidation' | 'performance' | 'persuasion';
+export type ProficiencyLevel = 'none' | 'proficient' | 'expertise';
+/**
+ * Game mode for stat progression
+ * - standard: D&D 5e rules (stats capped at 20, increases at levels 4, 8, 12, 16, 19, max level 20)
+ * - uncapped: No stat limits, stat increases EVERY level (unlimited progression)
+ */
+export type GameMode = 'standard' | 'uncapped';
+/**
+ * Attack type for combat actions
+ */
+export interface Attack {
+    name: string;
+    bonus?: number;
+    attack_bonus?: number;
+    damage?: string;
+    damage_dice?: string;
+    damage_type?: string;
+    type?: 'melee' | 'ranged' | 'spell';
+    range?: number;
+    /** Weapon properties (e.g., 'finesse', 'versatile', 'thrown', 'reach') */
+    properties?: string[];
+}
+/**
+ * Spell type for casting
+ *
+ * Unified spell interface that supports both player-facing spells (with
+ * damage_dice, damage_type, saving_throw) and enemy InnateSpell objects
+ * (with damage, damageType, save, tags, concentration, effect).
+ *
+ * SpellCaster checks both naming conventions so either field set works.
+ */
+export interface Spell {
+    name: string;
+    level?: number;
+    school?: string;
+    casting_time?: string;
+    /** Range as a string (e.g., "30 feet") — player spells */
+    range?: string;
+    /** Range as a number (feet) — enemy InnateSpell. Either range or rangeFeet may be set. */
+    rangeFeet?: number;
+    duration?: string;
+    components?: string[];
+    description?: string;
+    damage_dice?: string;
+    damage_type?: string;
+    attack_roll?: boolean;
+    saving_throw?: string;
+    /** Unique spell identifier (used by enemy InnateSpell) */
+    id?: string;
+    /** Spell effect description (used by enemy InnateSpell, separate from description) */
+    effect?: string;
+    /** Whether spell requires concentration */
+    concentration?: boolean;
+    /** Tags for spell classification (damage, healing, buff, control, aoe, etc.) */
+    tags?: string[];
+    /** Damage dice (alias for damage_dice — used by enemy InnateSpell) */
+    damage?: string;
+    /** Save ability (alias for saving_throw — used by enemy InnateSpell, e.g., "DEX") */
+    save?: string;
+    /** Damage type (alias for damage_type — used by enemy InnateSpell) */
+    damageType?: string;
+}
+export interface AbilityScores {
+    STR: number;
+    DEX: number;
+    CON: number;
+    INT: number;
+    WIS: number;
+    CHA: number;
+    dexterity?: number;
+    strength?: number;
+    constitution?: number;
+}
+export interface CharacterSheet {
+    /** Character name */
+    name: string;
+    /** Race */
+    race: Race;
+    /** Subrace (e.g., 'High Elf', 'Hill Dwarf', 'Wood Elf') */
+    subrace?: string;
+    /** Class */
+    class: Class;
+    /** Current level (1-20) */
+    level: number;
+    /** Ability scores */
+    ability_scores: AbilityScores;
+    /** Ability modifiers (calculated from scores) */
+    ability_modifiers: AbilityScores;
+    /** Proficiency bonus (based on level) */
+    proficiency_bonus: number;
+    /** Hit points */
+    hp: {
+        current: number;
+        max: number;
+        temp: number;
+    };
+    /** Armor class */
+    armor_class: number;
+    /** Initiative bonus */
+    initiative: number;
+    /** Speed in feet */
+    speed: number;
+    /** Skill proficiencies */
+    skills: Record<string, ProficiencyLevel>;
+    /** Saving throw proficiencies */
+    saving_throws: Record<Ability, boolean>;
+    /** Racial traits */
+    racial_traits: string[];
+    /** Class features */
+    class_features: string[];
+    /** Spells (for spellcasters) */
+    spells?: {
+        spell_slots: Record<number, {
+            total: number;
+            used: number;
+        }>;
+        known_spells: string[];
+        cantrips: string[];
+    };
+    /** Combat-ready Spell objects for use by CombatEngine and SpellCaster.
+     *  Populated from SpellcastingConfig during enemy generation.
+     *  Contains the full InnateSpell objects (which extend Spell) with
+     *  tags, damage, save, concentration, etc. — everything the AI needs
+     *  to make intelligent casting decisions. */
+    combat_spells?: Spell[];
+    /** Equipment */
+    equipment?: {
+        weapons: EnhancedInventoryItem[];
+        armor: EnhancedInventoryItem[];
+        items: EnhancedInventoryItem[];
+        totalWeight: number;
+        equippedWeight: number;
+    };
+    /** Character appearance */
+    appearance?: {
+        /** Deterministic features from seed */
+        body_type: string;
+        skin_tone: string;
+        hair_style: string;
+        hair_color: string;
+        eye_color: string;
+        facial_features: string[];
+        /** Dynamic features from audio/visual */
+        primary_color?: string;
+        secondary_color?: string;
+        accent_color?: string;
+        aura_color?: string;
+    };
+    /** Experience points */
+    xp: {
+        current: number;
+        next_level: number;
+    };
+    /** Track seed this character was generated from */
+    seed: string;
+    /** Generation timestamp */
+    generated_at: string;
+    /** Game mode for stat progression (standard = capped at 20, uncapped = no limits) */
+    gameMode?: GameMode;
+    /** Number of pending stat increases awaiting manual selection (counter) */
+    pendingStatIncreases?: number;
+    /**
+     * Prestige level for track mastery (0-10, defaults to 0)
+     * Higher prestige levels require more plays and XP to master a track
+     * @see PrestigeLevel
+     */
+    prestige_level?: PrestigeLevel;
+    /**
+     * Feature effects applied to this character
+     * Stores effects from features and traits that modify character stats
+     *
+     * Effects include:
+     * - stat_bonus: Add to ability scores (e.g., +1 STR)
+     * - skill_proficiency: Grant proficiency or expertise in a skill
+     * - ability_unlock: Unlock new abilities (e.g., darkvision, flight)
+     * - passive_modifier: Add constant bonuses (e.g., +10 speed)
+     * - resource_grant: Grant resource pools (e.g., rage counts, ki points)
+     * - spell_slot_bonus: Grant additional spell slots
+     */
+    feature_effects?: FeatureEffect[];
+    /**
+     * Equipment-granted effects
+     * Tracks effects currently active from equipped items
+     * Separate from feature_effects to allow proper removal when unequipping
+     *
+     * STACKING: All equipment effects stack (e.g., two +1 STR items = +2 STR total)
+     */
+    equipment_effects?: {
+        /** Equipment name providing the effect */
+        source: string;
+        /** Instance ID for per-instance tracking */
+        instanceId?: string;
+        /** Effects from this equipment */
+        effects: EquipmentProperty[];
+        /** Features granted by this equipment (registry features or inline mini-features) */
+        features: EquipmentFeature[];
+        /** Skills granted by this equipment */
+        skills: EquipmentSkill[];
+        /** Spells granted by this equipment */
+        spells?: EquipmentSpell[];
+    }[];
+    /**
+     * Legendary configuration for boss-tier enemies
+     * Contains legendary actions, resistances, and lair action hints
+     */
+    legendary_config?: {
+        /** Number of legendary resistances per day (usually 3 for CR 1-10) */
+        resistances_per_day: number;
+        /** Legendary actions available to this boss */
+        actions: Array<{
+            /** Unique identifier for this action */
+            id: string;
+            /** Display name shown to players */
+            name: string;
+            /** Cost in legendary action points (1, 2, or 3) */
+            cost: number;
+            /** Effect description for combat system */
+            effect: string;
+            /** Damage dice if this action deals damage */
+            damage?: string;
+            /** Damage type for damaging actions */
+            damage_type?: string;
+            /** Detailed description of what the action does */
+            description?: string;
+            /** Tags for filtering and categorization (e.g., 'damage', 'heal', 'control') */
+            tags?: string[];
+        }>;
+        /** Optional lair action hint for encounter design */
+        lair_action_hint?: string;
+    };
+    /**
+     * Stat level overrides for enemy characters
+     *
+     * When set, indicates that HP/attack/defense were scaled at independent
+     * effective levels rather than the CR-derived level. Enables creative
+     * encounter designs like glass cannons or tanks.
+     *
+     * For player characters: undefined
+     * For enemies: only set when statLevels was provided to EnemyGenerator.generate()
+     *
+     * @see StatLevelOverrides
+     */
+    stat_levels?: StatLevelOverrides;
+    /**
+     * Challenge Rating for enemy characters
+     * Used by EnemyGenerator to track the CR that was used to generate this enemy.
+     * This enables frontend validation that CR → level mapping is correct.
+     *
+     * For enemies: `cr` is the Challenge Rating used during generation
+     * For player characters: `cr` is undefined
+     *
+     * @example
+     * // Frontend validation: verify CR maps to correct level
+     * const enemy = EnemyGenerator.generate({ seed: 'test', cr: 8, rarity: 'elite' });
+     * console.log(enemy.cr);   // 8
+     * console.log(enemy.level); // 8 (CR ≈ level in D&D 5e)
+     */
+    cr?: number;
+}
+//# sourceMappingURL=Character.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Character.d.ts","sourceRoot":"","sources":["../../../src/core/types/Character.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EACR,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,cAAc,EAGd,qBAAqB,EACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE1C;AAoBD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,IAAI,EAAmC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CA6BzD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,YAAY,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAE5C;AAuBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,KAAK,EAAqC,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAmC3D;AAED,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEpE,MAAM,MAAM,KAAK,GACX,WAAW,GACX,YAAY,GACZ,iBAAiB,GACjB,SAAS,GACT,QAAQ,GACR,SAAS,GACT,eAAe,GACf,QAAQ,GACR,UAAU,GACV,iBAAiB,GACjB,SAAS,GACT,UAAU,GACV,YAAY,GACZ,UAAU,GACV,WAAW,GACX,cAAc,GACd,aAAa,GACb,YAAY,CAAC;AAEnB,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,MAAM;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,KAAK;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IAEZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC3B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,WAAW;IACX,IAAI,EAAE,IAAI,CAAC;IAEX,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,YAAY;IACZ,KAAK,EAAE,KAAK,CAAC;IAEb,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IAEd,qBAAqB;IACrB,cAAc,EAAE,aAAa,CAAC;IAE9B,iDAAiD;IACjD,iBAAiB,EAAE,aAAa,CAAC;IAEjC,yCAAyC;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAE1B,iBAAiB;IACjB,EAAE,EAAE;QACA,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,kBAAkB;IAClB,WAAW,EAAE,MAAM,CAAC;IAEpB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IAEd,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAEzC,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAExC,oBAAoB;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,qBAAqB;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB,gCAAgC;IAChC,MAAM,CAAC,EAAE;QACL,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC7D,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;IAEF;;;;iDAI6C;IAC7C,aAAa,CAAC,EAAE,KAAK,EAAE,CAAC;IAExB,gBAAgB;IAChB,SAAS,CAAC,EAAE;QACR,OAAO,EAAE,qBAAqB,EAAE,CAAC;QACjC,KAAK,EAAE,qBAAqB,EAAE,CAAC;QAC/B,KAAK,EAAE,qBAAqB,EAAE,CAAC;QAC/B,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF,2BAA2B;IAC3B,UAAU,CAAC,EAAE;QACT,uCAAuC;QACvC,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,EAAE,CAAC;QAE1B,yCAAyC;QACzC,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IAEF,wBAAwB;IACxB,EAAE,EAAE;QACA,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IAEb,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IAErB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,aAAa,EAAE,CAAC;IAElC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE;QAChB,0CAA0C;QAC1C,MAAM,EAAE,MAAM,CAAC;QAEf,4CAA4C;QAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;QAEpB,kCAAkC;QAClC,OAAO,EAAE,iBAAiB,EAAE,CAAC;QAE7B,qFAAqF;QACrF,QAAQ,EAAE,gBAAgB,EAAE,CAAC;QAE7B,uCAAuC;QACvC,MAAM,EAAE,cAAc,EAAE,CAAC;QAEzB,uCAAuC;QACvC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;KAC7B,EAAE,CAAC;IAEJ;;;OAGG;IACH,gBAAgB,CAAC,EAAE;QACf,sEAAsE;QACtE,mBAAmB,EAAE,MAAM,CAAC;QAE5B,+CAA+C;QAC/C,OAAO,EAAE,KAAK,CAAC;YACX,wCAAwC;YACxC,EAAE,EAAE,MAAM,CAAC;YAEX,oCAAoC;YACpC,IAAI,EAAE,MAAM,CAAC;YAEb,mDAAmD;YACnD,IAAI,EAAE,MAAM,CAAC;YAEb,2CAA2C;YAC3C,MAAM,EAAE,MAAM,CAAC;YAEf,8CAA8C;YAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;YAEhB,uCAAuC;YACvC,WAAW,CAAC,EAAE,MAAM,CAAC;YAErB,mDAAmD;YACnD,WAAW,CAAC,EAAE,MAAM,CAAC;YAErB,gFAAgF;YAChF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;SACnB,CAAC,CAAC;QAEH,qDAAqD;QACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAEjC;;;;;;;;;;;;;OAaG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CAEf"}

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

@@ -0,0 +1,169 @@
+/**
+ * Charted Beat Map Types
+ *
+ * Types for procedurally generated rhythm game charts that are compatible
+ * with BeatStream and the existing beat map infrastructure.
+ *
+ * Part of the Pitch Detection & Button Mapping pipeline - Phase 2.7
+ */
+import type { Beat, DownbeatConfig, SubdivisionType } from './BeatMap.js';
+import type { DifficultyLevel } from '../analysis/beat/DifficultyVariantGenerator.js';
+import type { Band } from '../generation/RhythmGenerator.js';
+/**
+ * A beat in a procedurally generated chart.
+ * Extends the base Beat interface with procedural-generation-specific fields.
+ */
+export interface ChartedBeat extends Beat {
+    /** Index into the original UnifiedBeatMap.beats[] - which quarter note this belongs to */
+    quarterNoteIndex: number;
+    /** Position within that quarter note (0-3 for 16th, 0-2 for triplet) */
+    subdivisionPosition: number;
+    /** Whether this was detected from audio (true) or interpolated/generated (false) */
+    isDetected: boolean;
+    /** The subdivision type used for this beat */
+    subdivisionType: SubdivisionType;
+    /** Which frequency band this beat originated from */
+    sourceBand: Band;
+    /** Quantization error in milliseconds (how far from original transient) */
+    quantizationError?: number;
+    /** Whether this beat's button was derived from pitch detection or pattern library */
+    mappingSource?: 'pitch' | 'pattern';
+    /** ID of the pattern used for this beat (if mappingSource is 'pattern') */
+    patternId?: string;
+}
+/**
+ * Metadata about a procedurally generated chart
+ */
+export interface ChartMetadata {
+    /** Which difficulty this chart represents */
+    difficulty: DifficultyLevel;
+    /** Keys used in this chart (e.g., ['up', 'down', 'left', 'right'] or ['1', '2', '3', '4', '5']) */
+    keysUsed: string[];
+    /** Number of beats with pitch-influenced keys */
+    pitchInfluencedBeats: number;
+    /** Button patterns used */
+    patternsUsed: string[];
+    /** Source rhythm metadata */
+    rhythmMetadata: RhythmMetadataSummary;
+    /** Pitch analysis metadata (if pitch detection was used) */
+    pitchMetadata: PitchMetadata | null;
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Seed used for reproducibility */
+    seed?: string;
+}
+/**
+ * Summary of rhythm metadata for chart output
+ */
+export interface RhythmMetadataSummary {
+    /** Difficulty preset used */
+    difficulty: string;
+    /** Bands that were analyzed */
+    bandsAnalyzed: Band[];
+    /** Total transients detected */
+    transientsDetected: number;
+    /** Average density across all bands */
+    averageDensity: number;
+    /** Natural difficulty of the composite */
+    naturalDifficulty: DifficultyLevel;
+}
+/**
+ * Metadata about pitch analysis used for chart generation
+ */
+export interface PitchMetadata {
+    /** Melody range detected (min and max note names) */
+    melodyRange: {
+        min: string;
+        max: string;
+    } | null;
+    /** Direction statistics from melody contour analysis */
+    directionStats: {
+        up: number;
+        down: number;
+        stable: number;
+        none: number;
+    } | null;
+    /** Interval statistics from melody contour analysis */
+    intervalStats: {
+        unison: number;
+        small: number;
+        medium: number;
+        large: number;
+        very_large: number;
+    } | null;
+}
+/**
+ * A complete procedurally-generated chart ready for gameplay.
+ * Compatible with BeatStream and the existing beat map infrastructure.
+ */
+export interface ChartedBeatMap {
+    /** Unique identifier for the audio source */
+    audioId: string;
+    /** Duration of the audio in seconds */
+    duration: number;
+    /** All beats with required keys assigned */
+    beats: ChartedBeat[];
+    /** Indices of beats that were originally detected from audio */
+    detectedBeatIndices: number[];
+    /** The downbeat configuration inherited from UnifiedBeatMap */
+    downbeatConfig: DownbeatConfig;
+    /** Quarter note interval in seconds (from UnifiedBeatMap) */
+    quarterNoteInterval: number;
+    /** Equivalent BPM (60 / quarterNoteInterval) */
+    bpm: number;
+    /** Chart metadata */
+    chartMetadata: ChartMetadata;
+}
+/**
+ * Options for converting a DifficultyVariant to ChartedBeatMap
+ */
+export interface ChartConversionOptions {
+    /** The audio ID for the chart */
+    audioId: string;
+    /** Duration of the audio in seconds */
+    duration: number;
+    /** Quarter note interval in seconds */
+    quarterNoteInterval: number;
+    /** Downbeat configuration */
+    downbeatConfig: DownbeatConfig;
+    /** Map of beat index to required key (from ButtonMapper) */
+    keyAssignments: Map<number, string>;
+    /** Chart metadata */
+    metadata: Partial<ChartMetadata>;
+}
+/**
+ * Maps procedural grid types to SubdivisionType
+ *
+ * @param gridType - The procedural grid type
+ * @returns The corresponding SubdivisionType
+ */
+export declare function mapGridToSubdivision(gridType: string): SubdivisionType;
+/**
+ * Calculate beatInMeasure from grid position
+ *
+ * @param parentBeatInMeasure - The parent quarter note's beatInMeasure value
+ * @param gridPosition - Position within that quarter (0-3 for 16th, 0-2 for triplet)
+ * @param gridType - The grid type
+ * @returns Decimal beatInMeasure value
+ */
+export declare function calculateBeatInMeasure(parentBeatInMeasure: number, gridPosition: number, gridType: string): number;
+import type { BeatMap } from './BeatMap.js';
+/**
+ * Convert a ChartedBeatMap to a BeatMap for use with BeatStream
+ *
+ * This adapter function creates a BeatMap-compatible object from a ChartedBeatMap,
+ * allowing procedurally generated charts to be used with the existing BeatStream
+ * infrastructure.
+ *
+ * @param chartedBeatMap - The ChartedBeatMap to convert
+ * @returns A BeatMap compatible with BeatStream
+ *
+ * @example
+ * ```typescript
+ * const chartedMap = beatConverter.convertToChartedBeatMap(variant, unifiedMap, keys, metadata);
+ * const beatMap = chartedBeatMapToBeatMap(chartedMap);
+ * const beatStream = new BeatStream(beatMap, audioContext);
+ * ```
+ */
+export declare function chartedBeatMapToBeatMap(chartedBeatMap: ChartedBeatMap): BeatMap;
+//# sourceMappingURL=ChartedBeatMap.d.ts.map

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

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