playlist-data-engine 1.1.0

package/dist/core/analysis/beat/utils/beatInterpolationDebug.d.ts

@@ -0,0 +1,404 @@
+/**
+ * Beat Interpolation Debug Utility
+ *
+ * Provides detailed debug output for the beat interpolation process.
+ * This tool is designed for research, development, and troubleshooting
+ * to understand how the interpolation algorithm works.
+ *
+ * @example
+ * ```typescript
+ * import { BeatInterpolator, generateDebugReport } from './beat/index.js';
+ *
+ * const interpolator = new BeatInterpolator();
+ * const interpolatedBeatMap = interpolator.interpolate(beatMap);
+ *
+ * // Generate a complete debug report
+ * const debugReport = generateDebugReport(interpolatedBeatMap);
+ * console.log(debugReport.toConsole());
+ *
+ * // Or save to JSON for later analysis
+ * const json = debugReport.toJSON();
+ * ```
+ */
+import type { Beat, BeatWithSource, InterpolatedBeatMap, QuarterNoteDetection } from '../../../types/BeatMap.js';
+/**
+ * A single entry in the quarter note detection histogram
+ */
+export interface HistogramEntry {
+    /** Interval bucket in seconds */
+    intervalSeconds: number;
+    /** Weight value for this bucket */
+    weight: number;
+    /** Whether this is the detected quarter note peak */
+    isPrimaryPeak: boolean;
+    /** Whether this is a secondary peak */
+    isSecondaryPeak: boolean;
+    /** Equivalent BPM for this interval */
+    bpm: number;
+}
+/**
+ * Information about a single gap between detected beats
+ */
+export interface GapDetail {
+    /** Index of the beat starting this gap */
+    startBeatIndex: number;
+    /** Index of the beat ending this gap */
+    endBeatIndex: number;
+    /** Timestamp of the start beat */
+    startTime: number;
+    /** Timestamp of the end beat */
+    endTime: number;
+    /** Duration of the gap in seconds */
+    duration: number;
+    /** Number of quarter notes that fit in this gap */
+    quarterNotesInGap: number;
+    /** Number of beats that were interpolated in this gap */
+    interpolatedBeats: number;
+    /** Whether this is a half-note gap (2x quarter note) */
+    isHalfNoteGap: boolean;
+    /** Whether this gap contains anomalies */
+    hasAnomalies: boolean;
+}
+/**
+ * Tempo drift data point
+ */
+export interface TempoDriftPoint {
+    /** Timestamp in seconds */
+    timestamp: number;
+    /** Local tempo in BPM at this point */
+    localTempo: number;
+    /** Beat index */
+    beatIndex: number;
+    /** Whether this is a detected or interpolated beat */
+    source: 'detected' | 'interpolated';
+    /** Deviation from the base tempo (percentage) */
+    deviationPercent: number;
+}
+/**
+ * Per-beat debug information
+ */
+export interface BeatDebugInfo {
+    /** Timestamp in seconds */
+    timestamp: number;
+    /** Beat index in the merged array */
+    index: number;
+    /** Source of this beat */
+    source: 'detected' | 'interpolated';
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Intensity value */
+    intensity: number;
+    /** Distance to nearest anchor (for interpolated beats) */
+    distanceToAnchor: number | null;
+    /** Timestamp of nearest anchor (for interpolated beats) */
+    nearestAnchorTimestamp: number | null;
+    /** Local tempo at this beat (BPM) */
+    localTempo: number;
+    /** Interval from previous beat (seconds) */
+    intervalFromPrevious: number | null;
+    /** Grid alignment error (seconds) */
+    gridAlignmentError: number;
+}
+/**
+ * Debug information for a tempo section
+ */
+export interface TempoSectionDebugInfo {
+    /** Section index (0-based) */
+    index: number;
+    /** Section start time in seconds */
+    start: number;
+    /** Section end time in seconds */
+    end: number;
+    /** Duration of section in seconds */
+    duration: number;
+    /** Tempo for this section in BPM */
+    bpm: number;
+    /** Quarter note interval in seconds */
+    intervalSeconds: number;
+    /** Number of detected beats in this section */
+    beatCount: number;
+    /** Index of first beat in this section */
+    startBeatIndex: number;
+    /** Index of last beat in this section */
+    endBeatIndex: number;
+    /** BPM change from previous section (null for first section) */
+    bpmChangeFromPrevious: number | null;
+    /** Percentage change from previous section (null for first section) */
+    percentChangeFromPrevious: number | null;
+}
+/**
+ * Multi-tempo debug information
+ */
+export interface MultiTempoDebugInfo {
+    /** Whether multi-tempo was detected */
+    hasMultipleTempos: boolean;
+    /** Whether multi-tempo analysis was applied */
+    hasMultiTempoApplied: boolean;
+    /** Detected cluster tempos from normal analysis */
+    detectedClusterTempos: number[];
+    /** Full tempo section data (only after multi-tempo re-analysis) */
+    sections: TempoSectionDebugInfo[];
+    /** Number of sections */
+    sectionCount: number;
+    /** BPM range (min to max) */
+    bpmRange: {
+        min: number;
+        max: number;
+        spread: number;
+    };
+}
+/**
+ * Complete debug report for beat interpolation
+ */
+export interface InterpolationDebugReport {
+    /** Audio ID */
+    audioId: string;
+    /** Audio duration in seconds */
+    duration: number;
+    /** When this report was generated */
+    generatedAt: string;
+    /** Quarter note detection debug info */
+    quarterNoteDetection: {
+        /** Detected interval in seconds */
+        intervalSeconds: number;
+        /** Equivalent BPM */
+        bpm: number;
+        /** Detection confidence */
+        confidence: number;
+        /** Method used for detection */
+        method: QuarterNoteDetection['method'];
+        /** Number of dense sections found */
+        denseSectionCount: number;
+        /** Total beats from dense sections */
+        denseSectionBeats: number;
+        /** Histogram data */
+        histogram: HistogramEntry[];
+    };
+    /** Gap analysis debug info */
+    gapAnalysis: {
+        /** Total number of gaps */
+        totalGaps: number;
+        /** Number of half-note gaps */
+        halfNoteGaps: number;
+        /** Number of anomalies detected */
+        anomalyCount: number;
+        /** Indices of anomalous beats */
+        anomalyIndices: number[];
+        /** Average gap size in quarter notes */
+        avgGapSize: number;
+        /** Grid alignment score (0-1) */
+        gridAlignmentScore: number;
+        /** Detailed gap information */
+        gaps: GapDetail[];
+    };
+    /** Per-beat debug information */
+    beats: BeatDebugInfo[];
+    /** Tempo drift over time */
+    tempoDrift: {
+        /** Base tempo in BPM */
+        baseTempo: number;
+        /** Minimum local tempo observed */
+        minTempo: number;
+        /** Maximum local tempo observed */
+        maxTempo: number;
+        /** Tempo drift ratio (max/min) */
+        driftRatio: number;
+        /** Data points for drift visualization */
+        dataPoints: TempoDriftPoint[];
+    };
+    /** Summary statistics */
+    summary: {
+        /** Total detected beats */
+        detectedBeatCount: number;
+        /** Total interpolated beats */
+        interpolatedBeatCount: number;
+        /** Total beats in merged output */
+        totalBeatCount: number;
+        /** Ratio of interpolated to total beats */
+        interpolationRatio: number;
+        /** Average confidence of interpolated beats */
+        avgInterpolatedConfidence: number;
+        /** Average confidence of detected beats */
+        avgDetectedConfidence: number;
+        /** Beats per second (overall density) */
+        beatsPerSecond: number;
+    };
+    /** Multi-tempo section debug info */
+    multiTempo: MultiTempoDebugInfo;
+}
+/**
+ * Options for debug output formatting
+ */
+export interface DebugOutputOptions {
+    /** Maximum number of beats to include in detailed output (0 = all) */
+    maxBeats?: number;
+    /** Whether to include histogram data */
+    includeHistogram?: boolean;
+    /** Whether to include gap details */
+    includeGapDetails?: boolean;
+    /** Whether to include per-beat debug info */
+    includeBeatDetails?: boolean;
+    /** Whether to include tempo drift data */
+    includeTempoDrift?: boolean;
+    /** Whether to include multi-tempo section data */
+    includeMultiTempo?: boolean;
+    /** Histogram bucket size in seconds */
+    histogramBucketSize?: number;
+}
+/**
+ * Default debug output options
+ */
+export declare const DEFAULT_DEBUG_OUTPUT_OPTIONS: Required<DebugOutputOptions>;
+/**
+ * Collect histogram data from a beat map
+ *
+ * Reconstructs the interval histogram used for quarter note detection.
+ *
+ * @param beats - Detected beats to analyze
+ * @param quarterNoteInterval - The detected quarter note interval
+ * @param bucketSize - Histogram bucket size in seconds
+ * @returns Array of histogram entries
+ */
+export declare function collectHistogramData(beats: Beat[], quarterNoteInterval: number, bucketSize?: number): HistogramEntry[];
+/**
+ * Collect detailed gap information
+ *
+ * @param detectedBeats - Original detected beats
+ * @param mergedBeats - Merged beats (interpolated + detected)
+ * @param quarterNoteInterval - Detected quarter note interval
+ * @param anomalies - Array of anomaly indices
+ * @returns Array of gap details
+ */
+export declare function collectGapDetails(detectedBeats: Beat[], mergedBeats: BeatWithSource[], quarterNoteInterval: number, anomalies: number[]): GapDetail[];
+/**
+ * Collect per-beat debug information
+ *
+ * @param mergedBeats - Merged beats array
+ * @param quarterNoteInterval - Detected quarter note interval
+ * @returns Array of beat debug info
+ */
+export declare function collectBeatDebugInfo(mergedBeats: BeatWithSource[], quarterNoteInterval: number): BeatDebugInfo[];
+/**
+ * Collect tempo drift data
+ *
+ * @param mergedBeats - Merged beats array
+ * @param baseTempo - Base tempo in BPM
+ * @returns Tempo drift data points and statistics
+ */
+export declare function collectTempoDriftData(mergedBeats: BeatWithSource[], baseTempo: number): {
+    minTempo: number;
+    maxTempo: number;
+    driftRatio: number;
+    dataPoints: TempoDriftPoint[];
+};
+/**
+ * Collect multi-tempo section debug information
+ *
+ * @param interpolationMetadata - The interpolation metadata from the beat map
+ * @returns Multi-tempo debug information
+ */
+export declare function collectMultiTempoDebugInfo(interpolationMetadata: InterpolatedBeatMap['interpolationMetadata']): MultiTempoDebugInfo;
+/**
+ * Generate a comprehensive debug report for an interpolated beat map
+ *
+ * @param interpolatedBeatMap - The interpolated beat map to analyze
+ * @param options - Debug output options
+ * @returns Complete debug report
+ */
+export declare function generateDebugReport(interpolatedBeatMap: InterpolatedBeatMap, options?: DebugOutputOptions): InterpolationDebugReport;
+/**
+ * Format a debug report as a human-readable console string
+ *
+ * @param report - Debug report to format
+ * @returns Formatted string for console output
+ */
+export declare function formatDebugReportToConsole(report: InterpolationDebugReport): string;
+/**
+ * Format a debug report as JSON
+ *
+ * @param report - Debug report to format
+ * @returns JSON string
+ */
+export declare function formatDebugReportToJSON(report: InterpolationDebugReport): string;
+/**
+ * Generate an ASCII visualization of tempo drift
+ *
+ * @param report - Debug report
+ * @param width - Width of the visualization in characters
+ * @returns ASCII visualization string
+ */
+export declare function generateTempoDriftVisualization(report: InterpolationDebugReport, width?: number): string;
+/**
+ * Generate an ASCII visualization of confidence scores over time
+ *
+ * @param report - Debug report
+ * @param width - Width of the visualization in characters
+ * @returns ASCII visualization string
+ */
+export declare function generateConfidenceVisualization(report: InterpolationDebugReport, width?: number): string;
+/**
+ * Generate an ASCII visualization of tempo sections
+ *
+ * Shows section boundaries and per-section tempos as a timeline.
+ *
+ * @param report - Debug report
+ * @param width - Width of the visualization in characters
+ * @returns ASCII visualization string
+ */
+export declare function generateTempoSectionVisualization(report: InterpolationDebugReport, width?: number): string;
+/**
+ * Debug helper class for beat interpolation
+ *
+ * Provides methods for generating and formatting debug output.
+ *
+ * @example
+ * ```typescript
+ * const interpolator = new BeatInterpolator();
+ * const interpolatedBeatMap = interpolator.interpolate(beatMap);
+ *
+ * const debug = new BeatInterpolationDebug(interpolatedBeatMap);
+ * console.log(debug.toConsole());
+ * debug.saveToFile('./debug-report.json');
+ * ```
+ */
+export declare class BeatInterpolationDebug {
+    private report;
+    constructor(interpolatedBeatMap: InterpolatedBeatMap, options?: DebugOutputOptions);
+    /**
+     * Get the raw debug report data
+     */
+    getReport(): InterpolationDebugReport;
+    /**
+     * Format as human-readable console output
+     */
+    toConsole(): string;
+    /**
+     * Format as JSON string
+     */
+    toJSON(): string;
+    /**
+     * Get tempo drift visualization
+     */
+    getTempoDriftVisualization(width?: number): string;
+    /**
+     * Get confidence visualization
+     */
+    getConfidenceVisualization(width?: number): string;
+    /**
+     * Get tempo section visualization
+     */
+    getTempoSectionVisualization(width?: number): string;
+    /**
+     * Print debug info to console
+     */
+    print(): void;
+    /**
+     * Save debug report to JSON file (Node.js only)
+     */
+    saveToFile(filePath: string): Promise<void>;
+    /**
+     * Load debug report from JSON file (Node.js only)
+     */
+    static loadFromFile(filePath: string): Promise<BeatInterpolationDebug>;
+}
+//# sourceMappingURL=beatInterpolationDebug.d.ts.map

package/dist/core/analysis/beat/utils/beatInterpolationDebug.d.ts.map

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

package/dist/core/analysis/beat/utils/subdivideBeatMap.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Beat Map Subdivision Convenience Function
+ *
+ * A one-step function that takes an InterpolatedBeatMap and SubdivisionConfig,
+ * unifies the beat map, and returns a SubdividedBeatMap.
+ *
+ * This is a convenience wrapper around `unifyBeatMap()` + `BeatSubdivider.subdivide()`.
+ *
+ * @example
+ * ```typescript
+ * const interpolator = new BeatInterpolator();
+ * const interpolatedMap = interpolator.interpolate(beatMap);
+ *
+ * // One-step subdivision with per-beat config
+ * const subdividedMap = subdivideBeatMap(interpolatedMap, {
+ *   beatSubdivisions: new Map([
+ *     [0, 'quarter'],
+ *     [32, 'eighth'],
+ *   ]),
+ *   defaultSubdivision: 'quarter',
+ * });
+ * ```
+ */
+import type { InterpolatedBeatMap, SubdividedBeatMap, SubdivisionConfig } from '../../../types/BeatMap.js';
+import { type BeatSubdividerOptions } from '../BeatSubdivider.js';
+/**
+ * Subdivide an interpolated beat map with a single function call
+ *
+ * This convenience function combines the unification and subdivision steps:
+ * 1. Converts InterpolatedBeatMap to UnifiedBeatMap
+ * 2. Applies the subdivision configuration
+ * 3. Returns the final SubdividedBeatMap
+ *
+ * @param interpolatedBeatMap - The interpolated beat map to subdivide
+ * @param config - Optional subdivision configuration (defaults to quarter notes)
+ * @param options - Optional BeatSubdivider options
+ * @returns A subdivided beat map
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default config (quarter notes)
+ * const subdividedMap = subdivideBeatMap(interpolatedMap);
+ *
+ * // With custom per-beat subdivision config
+ * const subdividedMap = subdivideBeatMap(interpolatedMap, {
+ *   beatSubdivisions: new Map([
+ *     [0, 'quarter'],
+ *     [32, 'eighth'],
+ *   ]),
+ *   defaultSubdivision: 'quarter',
+ * });
+ *
+ * // With subdivider options
+ * const subdividedMap = subdivideBeatMap(interpolatedMap, config, {
+ *   tolerance: 0.03,
+ *   defaultIntensity: 0.6,
+ * });
+ * ```
+ */
+export declare function subdivideBeatMap(interpolatedBeatMap: InterpolatedBeatMap, config?: SubdivisionConfig, options?: BeatSubdividerOptions): SubdividedBeatMap;
+//# sourceMappingURL=subdivideBeatMap.d.ts.map

package/dist/core/analysis/beat/utils/subdivideBeatMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subdivideBeatMap.d.ts","sourceRoot":"","sources":["../../../../../src/core/analysis/beat/utils/subdivideBeatMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACR,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACpB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAC5B,mBAAmB,EAAE,mBAAmB,EACxC,MAAM,GAAE,iBAA8C,EACtD,OAAO,CAAC,EAAE,qBAAqB,GAChC,iBAAiB,CASnB"}

package/dist/core/analysis/beat/utils/unifyBeatMap.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Beat Map Unification Utility
+ *
+ * Converts an InterpolatedBeatMap into a UnifiedBeatMap by flattening
+ * detected + interpolated beats into a single unified list of quarter notes.
+ * This is the foundation for the subdivision system.
+ *
+ * @example
+ * ```typescript
+ * const interpolator = new BeatInterpolator();
+ * const interpolatedMap = interpolator.interpolate(beatMap);
+ * const unifiedMap = unifyBeatMap(interpolatedMap);
+ *
+ * // All beats are now in a single array
+ * console.log(unifiedMap.beats.length);
+ *
+ * // Detected beat indices for accent patterns
+ * console.log(unifiedMap.detectedBeatIndices);
+ * ```
+ */
+import type { InterpolatedBeatMap, UnifiedBeatMap } from '../../../types/BeatMap.js';
+/**
+ * Convert an InterpolatedBeatMap to a UnifiedBeatMap
+ *
+ * This function flattens the merged beats (detected + interpolated) into a
+ * single unified list, removing the source distinction while preserving
+ * detected beat indices for accent pattern use.
+ *
+ * @param interpolatedBeatMap - The interpolated beat map to unify
+ * @returns A unified beat map ready for subdivision
+ */
+export declare function unifyBeatMap(interpolatedBeatMap: InterpolatedBeatMap): UnifiedBeatMap;
+//# sourceMappingURL=unifyBeatMap.d.ts.map

package/dist/core/analysis/beat/utils/unifyBeatMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unifyBeatMap.d.ts","sourceRoot":"","sources":["../../../../../src/core/analysis/beat/utils/unifyBeatMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACR,mBAAmB,EACnB,cAAc,EAGjB,MAAM,2BAA2B,CAAC;AAGnC;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,cAAc,CA4CrF"}

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

@@ -0,0 +1,18 @@
+/**
+ * Analysis Module
+ *
+ * Exports all audio analysis utilities.
+ */
+export { AudioAnalyzer } from './AudioAnalyzer.js';
+export { SpectrumScanner } from './SpectrumScanner.js';
+export { MusicClassifier } from './MusicClassifier.js';
+export { PitchDetector } from './PitchDetector.js';
+export { EssentiaPitchDetector, DEFAULT_CREPE_MODEL_URL } from './EssentiaPitchDetector.js';
+export type { EssentiaPitchAlgorithm, EssentiaPitchDetectorConfig, } from './EssentiaPitchDetector.js';
+export { MultiBandAnalyzer } from './MultiBandAnalyzer.js';
+export * from './beat/index.js';
+export { MelodyContourAnalyzer } from './MelodyContourAnalyzer.js';
+export type { MelodyContourAnalysisResult, MelodyContourAnalyzerConfig, DirectionStats, IntervalStats, IntervalCategory, PitchDirection, MelodyContour, MelodySegment, MelodySegmentDirection, MelodyContourDirection, } from './MelodyContourAnalyzer.js';
+export { PitchAnalyzer } from './PitchAnalyzer.js';
+export type { PitchAnalyzerConfig, PitchAnalysisProfile, PitchContour, PitchContourSegment, PitchContourSegmentDirection, PitchContourDirection, } from './PitchAnalyzer.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/analysis/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,YAAY,EACR,sBAAsB,EACtB,2BAA2B,GAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,cAAc,iBAAiB,CAAC;AAGhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,YAAY,EACR,2BAA2B,EAC3B,2BAA2B,EAC3B,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GACzB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACR,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,4BAA4B,EAC5B,qBAAqB,GACxB,MAAM,oBAAoB,CAAC"}

package/dist/core/combat/AI/AICombatRunner.d.ts

@@ -0,0 +1,108 @@
+/**
+ * AICombatRunner — Orchestrates full combat encounters with AI decision-making
+ *
+ * Bridges the gap between CombatAI (decisions) and CombatEngine (execution).
+ * For each combatant's turn, the runner:
+ * 1. Asks CombatAI for a decision
+ * 2. Executes the decision via CombatEngine
+ * 3. Processes legendary actions for bosses
+ * 4. Advances to the next turn
+ *
+ * The runner is designed for both live combat (random dice) and simulation
+ * (seeded dice). Pass a SeededDiceRoller for deterministic results.
+ */
+import type { CharacterSheet } from '../../types/Character.js';
+import type { CombatInstance, CombatConfig, CombatResult, DiceRollerAPI } from '../../types/Combat.js';
+import type { AIConfig, CombatantMetrics } from '../../types/CombatAI.js';
+/**
+ * Result of an AI-driven combat simulation.
+ * Contains both the full combat instance (with history) and the final result.
+ */
+export interface AICombatResult {
+    /** Full combat instance with complete action history */
+    combat: CombatInstance;
+    /** Final combat result (winner, XP, rounds, etc.) */
+    result: CombatResult;
+    /** Per-combatant metrics computed from combat history */
+    metrics: Map<string, CombatantMetrics>;
+}
+/**
+ * AICombatRunner — Runs a full combat encounter with AI-controlled combatants.
+ *
+ * Usage:
+ * ```ts
+ * const runner = new AICombatRunner();
+ * const { combat, result } = runner.runFullCombat(
+ *   players, enemies,
+ *   { playerStyle: 'normal', enemyStyle: 'aggressive' },
+ *   { maxTurnsBeforeDraw: 50 },
+ *   createSeededRoller('sim-seed-42')
+ * );
+ * console.log(result.winnerSide); // 'player' | 'enemy' | 'draw'
+ * console.log(result.roundsElapsed);
+ * ```
+ */
+export declare class AICombatRunner {
+    /**
+     * Run a complete combat encounter with AI-controlled combatants.
+     *
+     * @param players - Player character sheets
+     * @param enemies - Enemy character sheets
+     * @param aiConfig - AI configuration (play styles per side)
+     * @param combatConfig - Optional combat engine configuration
+     * @param diceRoller - Optional dice roller for deterministic simulation
+     * @returns The full combat instance and final result
+     */
+    runFullCombat(players: CharacterSheet[], enemies: CharacterSheet[], aiConfig: AIConfig, combatConfig?: CombatConfig, diceRoller?: DiceRollerAPI): AICombatResult;
+    /**
+     * Execute an AI decision on the combat engine.
+     *
+     * Maps each AIDecision action type to the corresponding CombatEngine method.
+     * Unhandled actions (e.g., useItem) are logged in history without mechanical effect.
+     */
+    private executeDecision;
+    /**
+     * Process legendary actions for boss enemies after a regular combatant's turn.
+     *
+     * In D&D 5e, legendary actions are taken at the end of another creature's turn.
+     * Each boss can spend up to 3 legendary action points per round. The AI
+     * decides whether to act and which action to use, potentially chaining
+     * multiple actions in a single turn.
+     */
+    private processLegendaryActions;
+    /**
+     * Execute a legendary action decision from the AI.
+     */
+    private executeLegendaryDecision;
+    /**
+     * Execute a weapon attack with resilience to weapon data issues.
+     *
+     * Handles the name mismatch between CombatAI's 'Unarmed Strike' and
+     * CombatEngine's 'unarmed' trigger. Falls back to unarmed strike if
+     * the named weapon causes an error (e.g., not in DEFAULT_EQUIPMENT).
+     */
+    private executeWeaponAttack;
+    /**
+     * Find a combatant by ID in the combat instance.
+     */
+    private findCombatant;
+    /**
+     * Find a spell by name from a combatant's combat_spells array.
+     */
+    private findSpell;
+    /**
+     * Resolve target combatants from a decision's target and targetIds fields.
+     */
+    private resolveTargets;
+    /**
+     * Fallback: basic attack the first living enemy when the preferred action
+     * can't be executed (e.g., flee not allowed).
+     */
+    private fallbackAttack;
+    /**
+     * Check if a combatant has any status effect that forces turn skipping
+     * (e.g., Stunned, Unconscious).
+     */
+    private hasSkipTurnEffect;
+}
+//# sourceMappingURL=AICombatRunner.d.ts.map

package/dist/core/combat/AI/AICombatRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AICombatRunner.d.ts","sourceRoot":"","sources":["../../../../src/core/combat/AI/AICombatRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EACV,cAAc,EAEd,YAAY,EACZ,YAAY,EACZ,aAAa,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAc,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAKtF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;IACvB,qDAAqD;IACrD,MAAM,EAAE,YAAY,CAAC;IACrB,yDAAyD;IACzD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;OASG;IACH,aAAa,CACX,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,EAAE,cAAc,EAAE,EACzB,QAAQ,EAAE,QAAQ,EAClB,YAAY,CAAC,EAAE,YAAY,EAC3B,UAAU,CAAC,EAAE,aAAa,GACzB,cAAc;IA6EjB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAgGvB;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAwB/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA+BhC;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAKrB;;OAEG;IACH,OAAO,CAAC,SAAS;IAKjB;;OAEG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAYtB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAK1B"}