playlist-data-engine 1.1.0

package/dist/core/combat/Analysis/DifficultyCalculator.d.ts

@@ -0,0 +1,203 @@
+/**
+ * DifficultyCalculator — Suggests enemy configurations for a target difficulty
+ * using simulation-driven binary search.
+ *
+ * Given a party and a desired difficulty, this class iteratively runs
+ * simulations at different CR values, adjusting up or down until the
+ * player win rate converges on the expected win rate range for the
+ * target difficulty.
+ *
+ * The search uses a two-phase approach:
+ * 1. **XP Budget Estimate** — `getCRFromXP()` provides the initial CR guess
+ *    based on D&D 5e encounter building math.
+ * 2. **Simulation-Driven Refinement** — binary search over CR values, running
+ *    simulations at each step to measure actual win rate, adjusting until
+ *    the win rate falls within the target range.
+ *
+ * Returns a `DifficultySuggestion` with the recommended CR, confidence
+ * interval, and the simulation data backing the recommendation.
+ *
+ * Usage:
+ * ```ts
+ * const calculator = new DifficultyCalculator();
+ * const suggestion = calculator.suggest(
+ *   party,
+ *   { rarity: 'elite', category: 'humanoid', archetype: 'brute' },
+ *   'medium',
+ *   { aiConfig: { playerStyle: 'normal', enemyStyle: 'aggressive' }, baseSeed: 'my-search' },
+ * );
+ * console.log(suggestion.recommendedCR);        // e.g., 3
+ * console.log(suggestion.winRate);              // e.g., 0.73
+ * console.log(suggestion.confidenceInterval);   // e.g., '72% ± 5%'
+ * ```
+ */
+import type { CharacterSheet } from '../../types/Character.js';
+import type { AIConfig } from '../../types/CombatAI.js';
+import type { CombatConfig } from '../../types/Combat.js';
+import type { EncounterDifficulty, EnemyRarity, EnemyCategory, EnemyArchetype, StatLevelOverrides } from '../../types/Enemy.js';
+/**
+ * Configuration for the difficulty calculation search.
+ */
+export interface DifficultyCalculatorOptions {
+    /** AI configuration for all simulations */
+    aiConfig: AIConfig;
+    /** Optional combat engine configuration */
+    combatConfig?: CombatConfig;
+    /** Base seed — each simulation iteration gets a derived seed */
+    baseSeed?: string;
+    /** Number of simulations to run per CR probe (default: 200) */
+    simulationsPerProbe?: number;
+    /**
+     * Maximum number of binary search iterations (default: 10).
+     * Each iteration runs a full simulation at one CR value.
+     */
+    maxIterations?: number;
+    /** Number of enemies in the encounter (default: 1) */
+    enemyCount?: number;
+    /** AbortSignal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Progress callback: (iteration, maxIterations, currentCR) */
+    onProgress?: (iteration: number, maxIterations: number, currentCR: number) => void;
+}
+/**
+ * Enemy template configuration for generating enemies during the search.
+ *
+ * The CR field is set automatically by the search — all other fields
+ * define the "template" enemy that gets generated at each CR level.
+ */
+export interface DifficultyEnemyTemplate {
+    /** Rarity tier (default: 'elite') */
+    rarity?: EnemyRarity;
+    /** Enemy category (default: 'humanoid') */
+    category?: EnemyCategory;
+    /** Combat archetype (default: 'brute') */
+    archetype?: EnemyArchetype;
+    /** Template ID for deterministic generation */
+    templateId?: string;
+    /** Stat level overrides */
+    statLevels?: StatLevelOverrides;
+    /** Difficulty multiplier */
+    difficultyMultiplier?: number;
+}
+/**
+ * A single probe point from the binary search.
+ * Records the CR tested and the simulation outcome.
+ */
+export interface DifficultyProbe {
+    /** CR value tested */
+    cr: number;
+    /** Player win rate from simulation */
+    winRate: number;
+    /** Total simulation runs */
+    totalRuns: number;
+    /** Average rounds to combat resolution */
+    averageRounds: number;
+    /** Average player HP remaining percent on winning runs */
+    averageHPRemaining: number;
+}
+/**
+ * Complete difficulty suggestion result.
+ *
+ * Contains the recommended CR, the simulation data backing it,
+ * confidence information, and the search history.
+ */
+export interface DifficultySuggestion {
+    /** The target difficulty */
+    targetDifficulty: EncounterDifficulty;
+    /**
+     * Recommended CR for a single enemy.
+     * For multi-enemy encounters, divide this by enemy count (approximately).
+     */
+    recommendedCR: number;
+    /** Player win rate at the recommended CR */
+    winRate: number;
+    /** Expected win rate range for the target difficulty */
+    expectedWinRateRange: {
+        min: number;
+        max: number;
+    };
+    /** Human-readable confidence interval string, e.g., "72% ± 5%" */
+    confidenceInterval: string;
+    /** Statistical margin of error (±) for the win rate */
+    marginOfError: number;
+    /** Whether the search converged on the target range */
+    converged: boolean;
+    /** Total simulations run across all probes */
+    totalSimulationsRun: number;
+    /** Number of search iterations performed */
+    iterationsUsed: number;
+    /** All probe points from the search (CR, winRate, etc.) */
+    probes: DifficultyProbe[];
+    /** XP-budget-based initial CR estimate (before simulation refinement) */
+    initialCREstimate: number;
+    /** The generated enemy CharacterSheet at the recommended CR */
+    suggestedEnemy: CharacterSheet;
+    /** Was the search cancelled before convergence? */
+    wasCancelled: boolean;
+}
+/**
+ * DifficultyCalculator — Suggests enemy CR for a target difficulty using
+ * simulation-driven binary search.
+ *
+ * Stateless between `suggest()` calls. Each call produces an independent
+ * `DifficultySuggestion`.
+ *
+ * The search works as follows:
+ * 1. Calculate XP budget for the party at the target difficulty
+ * 2. Adjust for encounter multiplier (enemy count)
+ * 3. Convert to CR estimate via `getCRFromXP()`
+ * 4. Run simulations at the estimated CR
+ * 5. If win rate is too high → increase CR; too low → decrease CR
+ * 6. Repeat until win rate is within target range or max iterations reached
+ */
+export declare class DifficultyCalculator {
+    private static readonly DEFAULT_SIMULATIONS_PER_PROBE;
+    private static readonly DEFAULT_MAX_ITERATIONS;
+    private static readonly CR_STEP_MIN;
+    private static readonly CR_FLOOR;
+    private static readonly CR_CEILING;
+    /**
+     * Suggest an enemy CR for the given party and target difficulty.
+     *
+     * @param players - Player character sheets
+     * @param enemyTemplate - Template for generating enemies (rarity, category, etc.)
+     * @param targetDifficulty - The desired encounter difficulty
+     * @param options - Calculator options (AI config, seed, probe count, etc.)
+     * @returns Complete difficulty suggestion with recommended CR and simulation data
+     */
+    suggest(players: CharacterSheet[], enemyTemplate: DifficultyEnemyTemplate, targetDifficulty: EncounterDifficulty, options: DifficultyCalculatorOptions): DifficultySuggestion;
+    /**
+     * Run a simulation probe at a given CR and return the summary.
+     */
+    private runProbe;
+    /**
+     * Generate enemies from the template at the given CR.
+     */
+    private generateEnemies;
+    /**
+     * Generate a single enemy from the template at the given CR.
+     */
+    private generateEnemy;
+    /**
+     * Calculate margin of error for a proportion using the normal approximation.
+     *
+     * MOE = z * sqrt(p * (1 - p) / n) at 95% confidence (z = 1.96)
+     */
+    private calculateMarginOfError;
+    /**
+     * Format a confidence interval as a human-readable string.
+     *
+     * Example: "72% ± 5%"
+     */
+    private formatConfidenceInterval;
+    /**
+     * Round CR to a standard D&D value (0.125, 0.25, 0.5, or integer).
+     *
+     * Maps fractional CRs to the nearest standard step:
+     * - < 0.25 → 0.125
+     * - < 0.75 → 0.5
+     * - otherwise → nearest integer
+     */
+    private roundCR;
+}
+//# sourceMappingURL=DifficultyCalculator.d.ts.map

package/dist/core/combat/Analysis/DifficultyCalculator.d.ts.map

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

package/dist/core/combat/Analysis/ParameterSweep.d.ts

@@ -0,0 +1,201 @@
+/**
+ * ParameterSweep — Systematically vary a single encounter parameter and
+ * collect simulation results at each data point.
+ *
+ * Answers questions like: "What CR makes this a Medium encounter?" or
+ * "How does adding more enemies change the win rate curve?"
+ *
+ * Usage:
+ * ```ts
+ * const sweeper = new ParameterSweep();
+ * const results = sweeper.sweep(
+ *   party,
+ *   { cr: 3, rarity: 'elite', category: 'humanoid', archetype: 'brute' },
+ *   {
+ *     variable: 'cr',
+ *     range: { min: 1, max: 10, step: 1 },
+ *     simulationsPerPoint: 200,
+ *     aiConfig: { playerStyle: 'normal', enemyStyle: 'aggressive' },
+ *   },
+ *   (point, total) => console.log(`Sweep ${point}/${total}`)
+ * );
+ * // results.dataPoints[i].parameterValue → CR value
+ * // results.dataPoints[i].playerWinRate → win rate at that CR
+ * ```
+ */
+import type { CharacterSheet } from '../../types/Character.js';
+import type { AIConfig } from '../../types/CombatAI.js';
+import type { EnemyRarity, EnemyArchetype, EnemyCategory, StatLevelOverrides } from '../../types/Enemy.js';
+/**
+ * Which encounter parameter to vary across the sweep.
+ *
+ * Each variable modifies either the enemy generation options or the party
+ * configuration before running simulations at that data point.
+ */
+export type SweepVariable = 'cr' | 'enemyCount' | 'partyLevel' | 'difficultyMultiplier' | 'rarity' | 'hpLevel' | 'attackLevel' | 'defenseLevel';
+/**
+ * Range configuration for the sweep variable.
+ *
+ * Generates data points from `min` to `max` (inclusive) at `step` intervals.
+ * For example: `{ min: 1, max: 10, step: 1 }` produces 10 data points.
+ */
+export interface SweepRange {
+    /** Starting value of the parameter */
+    min: number;
+    /** Ending value of the parameter (inclusive) */
+    max: number;
+    /** Step size between data points */
+    step: number;
+}
+/**
+ * Configuration for a parameter sweep.
+ *
+ * Defines which parameter to vary, over what range, and with how many
+ * simulations per data point.
+ */
+export interface SweepParams {
+    /** Which parameter to vary */
+    variable: SweepVariable;
+    /** Range of values to sweep across */
+    range: SweepRange;
+    /** Number of simulations to run at each data point */
+    simulationsPerPoint: number;
+    /** AI configuration for all simulations */
+    aiConfig: AIConfig;
+    /** Optional combat engine configuration */
+    combatConfig?: import('../../types/Combat.js').CombatConfig;
+    /** Base seed — each data point gets baseSeed + '-' + parameterValue */
+    baseSeed?: string;
+    /** AbortSignal for cancelling the sweep */
+    abortSignal?: AbortSignal;
+}
+/**
+ * A single data point in the sweep results.
+ *
+ * Maps a parameter value to the simulation summary at that value.
+ */
+export interface SweepDataPoint {
+    /** The value of the sweep parameter at this data point */
+    parameterValue: number;
+    /** Player win rate (0.0–1.0) at this parameter value */
+    playerWinRate: number;
+    /** Average number of rounds to combat resolution */
+    averageRounds: number;
+    /** Average player HP remaining percent on winning runs */
+    averageHPRemaining: number;
+    /** Total player deaths across all simulations at this point */
+    totalPlayerDeaths: number;
+    /** Total enemy deaths across all simulations at this point */
+    totalEnemyDeaths: number;
+    /** Median rounds to combat resolution */
+    medianRounds: number;
+}
+/**
+ * Complete results from a parameter sweep.
+ *
+ * Contains one `SweepDataPoint` per value in the sweep range, ordered
+ * from lowest parameter value to highest.
+ */
+export interface SweepResults {
+    /** Which parameter was swept */
+    variable: SweepVariable;
+    /** The range that was swept */
+    range: SweepRange;
+    /** Number of simulations run at each data point */
+    simulationsPerPoint: number;
+    /** Data points mapping parameter value → simulation summary */
+    dataPoints: SweepDataPoint[];
+    /** Whether the sweep was cancelled before completing all data points */
+    wasCancelled: boolean;
+}
+/**
+ * Base enemy configuration for the sweep.
+ *
+ * Defines the "template" enemy that gets modified by the sweep variable.
+ */
+export interface SweepEnemyConfig {
+    /** Challenge Rating (used as default, overridden when variable='cr') */
+    cr?: number;
+    /** Rarity tier */
+    rarity?: EnemyRarity;
+    /** Enemy category */
+    category?: EnemyCategory;
+    /** Combat archetype */
+    archetype?: EnemyArchetype;
+    /** Template ID for deterministic generation */
+    templateId?: string;
+    /** Stat level overrides */
+    statLevels?: StatLevelOverrides;
+    /** Difficulty multiplier */
+    difficultyMultiplier?: number;
+}
+/**
+ * ParameterSweep — Varies a single encounter parameter across a range
+ * and runs simulations at each data point.
+ *
+ * Stateless between `sweep()` calls. Each sweep produces an independent
+ * set of results.
+ */
+export declare class ParameterSweep {
+    /**
+     * Run a parameter sweep.
+     *
+     * For each value in the sweep range, generates enemies (or modifies party)
+     * with that parameter value, runs simulations, and collects the summary.
+     *
+     * @param players - Player character sheets (original, unmodified)
+     * @param baseEncounter - Base enemy configuration (modified per data point)
+     * @param params - Sweep configuration (variable, range, simulations per point)
+     * @param onProgress - Optional callback: (completedPoints, totalPoints)
+     * @returns SweepResults with one data point per value in the range
+     */
+    sweep(players: CharacterSheet[], baseEncounter: SweepEnemyConfig, params: SweepParams, onProgress?: (completed: number, total: number) => void): SweepResults;
+    /**
+     * Generate the list of parameter values from a range.
+     */
+    private generateValues;
+    /**
+     * Apply a parameter value to the base party/encounter configuration.
+     *
+     * Returns modified copies — the originals are never mutated.
+     */
+    private applyParameter;
+    /**
+     * Sweep CR: generate enemies at the given CR.
+     */
+    private applyCR;
+    /**
+     * Sweep enemy count: generate N enemies with the base config.
+     */
+    private applyEnemyCount;
+    /**
+     * Sweep party level: scale all player character levels to the given value.
+     *
+     * Creates shallow copies with adjusted level and derives reasonable stat changes.
+     * Note: this is a simplified scaling — real level-up involves class-specific features.
+     */
+    private applyPartyLevel;
+    /**
+     * Sweep difficulty multiplier: generate enemies with the given multiplier.
+     */
+    private applyDifficultyMultiplier;
+    /**
+     * Sweep rarity: map numeric value to rarity tier (0=common, 1=uncommon, 2=elite, 3=boss).
+     */
+    private applyRarity;
+    /**
+     * Sweep a stat level override (hpLevel, attackLevel, or defenseLevel).
+     */
+    private applyStatLevel;
+    /**
+     * Generate enemies from the encounter config.
+     *
+     * Generates `count` enemies, each with a unique seed derived from the config.
+     */
+    private generateEnemies;
+    /**
+     * Extract a SweepDataPoint from a SimulationSummary.
+     */
+    private summarizeToPoint;
+}
+//# sourceMappingURL=ParameterSweep.d.ts.map

package/dist/core/combat/Analysis/ParameterSweep.d.ts.map

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

package/dist/core/combat/AttackResolver.d.ts

@@ -0,0 +1,220 @@
+/**
+ * AttackResolver - Handles melee and ranged attack resolution
+ * D&D 5e: d20 + attack bonus vs target AC
+ * Critical hits (natural 20) double damage dice
+ * Critical misses (natural 1) always miss
+ */
+import type { Combatant, AttackRoll, DamageRoll, DiceRollerAPI, HitMode } from '../types/Combat';
+import type { Attack, CharacterSheet, AbilityScores } from '../types/Character';
+/**
+ * Result of a complete attack action
+ */
+export interface AttackResult {
+    attacker: Combatant;
+    target: Combatant;
+    attack: Attack;
+    attackRoll: AttackRoll;
+    damageRoll?: DamageRoll;
+    hpAfterDamage?: number;
+    description: string;
+}
+/**
+ * Result of simulating multiple attack rolls
+ */
+export interface AttackSimulationResult {
+    iterations: number;
+    totalHits: number;
+    totalMisses: number;
+    totalCrits: number;
+    hitRate: number;
+    critRate: number;
+    missRate: number;
+    averageDamage: number;
+    maxDamage: number;
+    /** Sorted array of { damage, count, percentage } from 0 (misses) upward */
+    distribution: Array<{
+        damage: number;
+        count: number;
+        percentage: number;
+    }>;
+}
+/**
+ * AttackResolver - D&D 5e attack and damage calculation
+ */
+export declare class AttackResolver {
+    private diceRoller?;
+    private hitMode;
+    constructor(diceRoller?: DiceRollerAPI, hitMode?: HitMode);
+    /**
+     * Compute scaled mode damage from raw stats.
+     *
+     * Formula: max(1, levelBase + weaponBonus)
+     * - levelBase = max(1, floor(level * 2 + (STR - AC) * 0.3))
+     * - weaponBonus = getWeaponBonus(damageDice)
+     * - Crits multiply levelBase by 1.5x (weapon bonus unaffected).
+     *
+     * NOTE: Always uses STR, even for finesse weapons (by design).
+     */
+    static computeScaledDamage(level: number, str: number, targetAC: number, damageDice: string, isCritical: boolean): number;
+    /**
+     * Compute the damage scale factor for a below-AC roll in scaled mode.
+     *
+     * Returns 1.0 if totalRoll >= targetAC (full damage).
+     * Otherwise returns max(0.10, 1 - deficit * 0.10).
+     */
+    static computeDamageScale(totalRoll: number, targetAC: number): number;
+    /**
+     * Compute the attack bonus for a weapon.
+     *
+     * DEX for ranged or finesse weapons, STR otherwise.
+     * Matches CombatEngine.buildWeaponAttack.
+     */
+    static computeAttackBonus(abilityScores: AbilityScores, weaponProperties: string[], proficiency: number): number;
+    /**
+     * Resolve an attack action
+     * 1. Roll d20 + attack bonus
+     * 2. Compare to target AC
+     * 3. If hit, roll damage
+     */
+    resolveAttack(attacker: Combatant, target: Combatant, attack: Attack): AttackResult;
+    /**
+     * Roll an attack (d20 + attack bonus vs AC)
+     * Attack bonus = ability modifier + proficiency bonus (if proficient)
+     *
+     * Hit modes:
+     * - 'dnd': Classic — totalRoll >= AC to hit. Nat 1 miss, nat 20 crit.
+     * - 'scaled': AC reduces damage. Only nat 1 misses, nat 20 crits.
+     *   Each point below AC reduces damage by 10% (min 10%).
+     */
+    private rollAttack;
+    /**
+     * Roll damage for an attack.
+     *
+     * Hit mode determines the damage system:
+     *
+     * 'dnd' — Traditional dice-based damage (D&D 5e style).
+     *   Rolls weapon dice + ability modifier. Crits double the dice.
+     *
+     * 'scaled' — Formula-based damage (Pokemon/Earthbound style).
+     *   No dice rolls. Damage = max(1, floor(attackerLevel * 2 + (STR - AC) * 0.3)).
+     *   Crits multiply by 1.5x. Scales smoothly with level — starts low (1-2 at
+     *   level 1) and grows with stat gaps at higher levels.
+     */
+    private rollDamage;
+    /**
+     * Extracts the ability modifier to apply to damage rolls.
+     *
+     * - Ranged attacks use DEX modifier.
+     * - Finesse melee weapons use max(STR, DEX).
+     * - Other melee attacks use STR modifier.
+     * - Spells return 0 (ability mod not added to damage dice).
+     */
+    private getDamageModifier;
+    /**
+     * DND mode: traditional dice-based damage.
+     * Rolls weapon dice + ability modifier (STR for melee, DEX for finesse/ranged).
+     * Crits double the dice (not the modifier).
+     */
+    private rollDamageDND;
+    /**
+     * Scaled mode: formula-based damage (no dice rolls).
+     *
+     * Formula: max(1, levelBase + weaponBonus)
+     * - levelBase = max(1, floor(attackerLevel * 2 + (STR - AC) * 0.3))
+     * - weaponBonus = round(avgDiceRoll / 2.5)
+     *
+     * Level is the primary driver. The weapon's die size provides a flat bonus
+     * based on its tier (d4→1, d6→1, d8→2, d10→2, d12→3) so weapon choice
+     * matters without dice variance. Crits multiply levelBase by 1.5x.
+     */
+    private rollDamageScaled;
+    /**
+     * Convert a damage dice string to a flat weapon bonus.
+     * Uses the dice average divided by 2.5, giving clean tiers:
+     * d4→1, d6→1, d8→2, d10→2, d12→3, 2d6→3, 2d8→4
+     */
+    static getWeaponBonus(damageDice?: string): number;
+    /**
+     * Format weapon damage for display based on the damage display mode.
+     *
+     * 'scaled': Shows flat damage bonus derived from the dice (e.g. "+2 piercing")
+     * 'dnd':    Shows the raw dice string (e.g. "1d8 piercing")
+     */
+    static formatWeaponDamage(dice: string, damageType: string, damageDisplay: 'dnd' | 'scaled'): string;
+    /**
+     * Estimate average damage per hit for a given hitMode.
+     *
+     * This mirrors the actual combat damage formulas so pre-simulation
+     * estimates match what the simulator produces.
+     *
+     * - 'scaled': `max(1, floor(level * 2 + (STR - targetAC) * 0.3)) + weaponBonus`
+     *   NOTE: Scaled mode always uses STR (matches rollDamageScaled).
+     * - 'dnd':    dice average + ability modifier (caller picks STR or DEX)
+     */
+    static estimateDamagePerHit(opts: {
+        hitMode: HitMode;
+        level: number;
+        abilityScore: number;
+        targetAC: number;
+        damageDice: string;
+        proficiencyBonus?: number;
+    }): number;
+    /**
+     * Estimate Damage Per Round including hit rate.
+     *
+     * Iterates over all 20 d20 outcomes to compute the true average,
+     * matching the actual combat mechanics exactly:
+     *
+     * - 'scaled': Only nat 1 misses. Rolls below AC deal scaled damage
+     *   (max(10%, 1 - deficit * 10%)). Always uses STR for the damage
+     *   formula (matches rollDamageScaled).
+     * - 'dnd':    `max(5%, (21 - (targetAC - attackBonus)) / 20)` hit rate.
+     */
+    static estimateDPR(opts: {
+        hitMode: HitMode;
+        level: number;
+        abilityScore: number;
+        targetAC: number;
+        damageDice: string;
+        proficiencyBonus?: number;
+        attackBonus?: number;
+        attackCount?: number;
+    }): number;
+    /**
+     * Check if an attack is within range
+     * Melee attacks: must be adjacent (5 ft)
+     * Ranged attacks: must be within attack range
+     */
+    isInRange(attacker: Combatant, target: Combatant, attack: Attack): boolean;
+    /**
+     * Calculate attack bonus for a character
+     * Ability modifier + proficiency bonus (if proficient with weapon)
+     */
+    calculateAttackBonus(character: CharacterSheet, _attackName: string, abilityModifier: number, isProficient?: boolean): number;
+    /**
+     * Check if attack hits with advantage or disadvantage
+     * D&D 5e rules: With advantage, critical if EITHER die is a 20
+     */
+    attackWithAdvantage(attacker: Combatant, target: Combatant, attack: Attack): AttackResult;
+    /**
+     * Attack with disadvantage
+     * D&D 5e rules: Roll twice, take lower. If EITHER die is a 1, it's a critical miss
+     */
+    attackWithDisadvantage(attacker: Combatant, target: Combatant, attack: Attack): AttackResult;
+    /**
+     * Simulate N attack rolls using the full engine attack resolution pipeline.
+     *
+     * Creates fresh Combatant wrappers each iteration so the target's HP is never
+     * permanently mutated. Uses the same resolveAttack logic as live combat
+     * (d20 + attack bonus vs AC, crit on nat 20, fumble on nat 1, doubled dice
+     * on crits, ability-modifier-based damage calculation).
+     *
+     * @param attacker  Character sheet of the attacking hero/enemy
+     * @param target    Character sheet of the defender
+     * @param attack    Attack object (weapon or spell) with damage_dice and attack_bonus
+     * @param iterations  Number of attacks to simulate (default 1000)
+     * @param diceRoller  Optional seeded/custom dice roller
+     */
+    static simulateAttacks(attacker: CharacterSheet, target: CharacterSheet, attack: Attack, iterations?: number, diceRoller?: DiceRollerAPI, hitMode?: HitMode): AttackSimulationResult;
+}
+//# sourceMappingURL=AttackResolver.d.ts.map

package/dist/core/combat/AttackResolver.d.ts.map

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