playlist-data-engine 1.1.0

package/dist/core/analysis/beat/DifficultyVariantGenerator.d.ts

@@ -0,0 +1,1082 @@
+/**
+ * Difficulty Variant Generator for Procedural Rhythm Generation
+ *
+ * Generates difficulty variants (easy/medium/hard) from the composite stream
+ * by simplifying or enhancing density based on natural difficulty.
+ *
+ * Part of the Procedural Rhythm Generation pipeline - Phase 3.3
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - generate all 3 difficulty variants
+ * const generator = new DifficultyVariantGenerator();
+ * const variants = generator.generateAll(compositeStream, phraseAnalysis, gridDecisions);
+ *
+ * // Access each difficulty variant
+ * const easyVariant = variants.easy;
+ * const mediumVariant = variants.medium;
+ * const hardVariant = variants.hard;
+ *
+ * // Check which variant is unedited (natural difficulty)
+ * console.log(`Easy is unedited: ${easyVariant.isUnedited}`);
+ * console.log(`Medium is unedited: ${mediumVariant.isUnedited}`);
+ * console.log(`Hard is unedited: ${hardVariant.isUnedited}`);
+ *
+ * // Check edit details
+ * console.log(`Medium edit type: ${mediumVariant.editType}`);
+ * console.log(`Medium edit amount: ${mediumVariant.editAmount.toFixed(2)}`);
+ *
+ * // Custom configuration for phrase boundary preservation
+ * const customGenerator = new DifficultyVariantGenerator({
+ *   preservePhraseBoundaries: true,
+ *   logConversions: true,
+ * });
+ * ```
+ */
+import type { CompositeBeat, CompositeStream } from './CompositeStreamGenerator.js';
+import type { NaturalDifficulty } from './DensityAnalyzer.js';
+import type { GridType, GridDecision } from './RhythmQuantizer.js';
+import type { PhraseAnalysisResult } from './PhraseAnalyzer.js';
+import type { UnifiedBeatMap } from '../../types/BeatMap.js';
+import type { RhythmicBalanceConfig } from './RhythmicBalancer.js';
+/**
+ * Extended grid type including simplified subdivisions for Easy difficulty
+ *
+ * - `straight_16th`: Standard 16th note grid (4 positions per beat: 0, 1, 2, 3)
+ * - `triplet_8th`: 8th note triplet grid (3 positions per beat: 0, 1, 2)
+ * - `straight_8th`: Standard 8th note grid (2 positions per beat: 0, 2)
+ * - `quarter_triplet`: Quarter note triplet (1 position per beat, triplet feel)
+ * - `straight_4th`: Quarter note grid (1 position per beat: 0) — Easy at BPM > 120
+ */
+export type ExtendedGridType = GridType | 'straight_8th' | 'quarter_triplet' | 'straight_4th';
+/**
+ * All possible grid types for reference
+ */
+export declare const ALL_GRID_TYPES: ExtendedGridType[];
+/**
+ * Subdivision limits for each difficulty level
+ *
+ * This constant defines which grid types are allowed for each difficulty
+ * at slow tempos (BPM < 70). For tempo-aware limits, use
+ * `getTempoAwareAllowedGridTypes()`.
+ *
+ * Easy and Medium have no tempo-dependent variation — their grid restrictions
+ * apply at all BPMs. Hard allows all types only at BPM < 70.
+ *
+ * | Difficulty | BPM < 70 | 70 ≤ BPM ≤ 120 | BPM > 120 |
+ * |------------|----------|----------------|-----------|
+ * | Easy | `straight_4th`, `quarter_triplet` | same | same |
+ * | Medium | `straight_8th`, `quarter_triplet` | same | same |
+ * | Hard | All types | `straight_8th`, `quarter_triplet` | same |
+ * | Natural | All types | All types | All types |
+ *
+ * @example
+ * ```typescript
+ * // Check if a grid type is allowed for a difficulty at a given BPM
+ * const allowed = getTempoAwareAllowedGridTypes('medium', 120);
+ * // ['straight_8th', 'quarter_triplet'] — 16th notes restricted at ≥70 BPM
+ * ```
+ */
+export declare const SUBDIVISION_LIMITS: Record<DifficultyLevel, SubdivisionLimitConfig>;
+/** BPM threshold: medium restricts 16th/triplet_8th at or above this value */
+export declare const MEDIUM_RESTRICT_BPM = 70;
+/** BPM threshold: hard restricts 16th/triplet_8th at or above this value */
+export declare const HARD_RESTRICT_BPM = 70;
+/** BPM threshold: easy restricts to quarter notes above this value */
+export declare const EASY_QUARTER_NOTE_BPM = 120;
+/**
+ * Get the allowed grid types for a difficulty at a given BPM.
+ *
+ * This function returns the effective subdivision limits after applying
+ * tempo-based restrictions:
+ *
+ * - **Easy**: Always `straight_4th` (quarter notes) and `quarter_triplet`.
+ *   8th notes are too rapid for beginners at any tempo.
+ * - **Medium**: Always `straight_8th` and `quarter_triplet`.
+ *   16th notes and 8th note triplets are reserved for hard/natural.
+ * - **Hard at BPM ≥ 70**: Only `straight_8th` and `quarter_triplet`.
+ *   16th notes and 8th note triplets are reserved for natural/custom at higher tempos.
+ * - **Natural**: Always all types (no restrictions).
+ *
+ * @param difficulty - The difficulty level
+ * @param bpm - The tempo in beats per minute
+ * @returns Array of allowed grid types
+ */
+export declare function getTempoAwareAllowedGridTypes(difficulty: DifficultyLevel, bpm: number): ExtendedGridType[];
+/**
+ * Derive allowed grid types from a DensityGenerationConfig and BPM.
+ *
+ * This is the core helper for density-based generation. It:
+ * 1. Looks up the base set of allowed grid types from the hierarchy based on `maxGridType`
+ * 2. Optionally applies BPM-based restrictions if `bpmBasedQuantization` is true
+ *
+ * @param config - The density generation configuration
+ * @param bpm - Current BPM for tempo-aware restrictions
+ * @returns Array of allowed ExtendedGridType values
+ */
+export declare function deriveAllowedGridTypes(config: DensityGenerationConfig, bpm: number): ExtendedGridType[];
+/**
+ * Calculate the maximum achievable density (notes/second) for a given set of
+ * allowed grid types at a specific BPM.
+ *
+ * This is used to detect impossible configurations (e.g., requesting 4.0 nps
+ * with only 8th notes at 60 BPM, where max achievable is ~2.0 nps).
+ *
+ * @param allowedGridTypes - The grid types that are allowed
+ * @param bpm - Current BPM
+ * @returns Maximum achievable density in notes/second
+ */
+export declare function calculateMaxAchievableDensity(allowedGridTypes: ExtendedGridType[], bpm: number): number;
+/**
+ * Difficulty level for rhythm variants
+ *
+ * - 'easy': Simplified rhythm with 8th notes max
+ * - 'medium': Moderate difficulty with density reduction
+ * - 'hard': Full density with all subdivisions
+ * - 'natural': Unedited composite stream (what was actually detected)
+ * - 'custom': Custom density-based variant — parameters provided at generation time
+ */
+export type DifficultyLevel = 'easy' | 'medium' | 'hard' | 'natural' | 'custom';
+/**
+ * Preset difficulty levels (excludes 'custom')
+ *
+ * Used for GeneratedRhythm.difficultyVariants which only contains preset variants.
+ * Custom variants are generated standalone via generateAtDensity().
+ */
+export type PresetDifficultyLevel = 'easy' | 'medium' | 'hard' | 'natural';
+/**
+ * Configuration for density-based level generation
+ *
+ * Provides independent control over target density (notes/second) and maximum
+ * quantization grid, enabling a continuous spectrum of difficulty alongside
+ * the existing easy/medium/hard/natural presets.
+ *
+ * @example
+ * ```typescript
+ * // Dense chart with only 8th note quantization
+ * const config: DensityGenerationConfig = {
+ *   targetDensity: 3.0,
+ *   maxGridType: 'straight_8th'
+ * };
+ *
+ * // Sparse chart with 16th note quantization allowed
+ * const config: DensityGenerationConfig = {
+ *   targetDensity: 0.5,
+ *   maxGridType: 'straight_16th'
+ * };
+ *
+ * // With BPM-based quantization restrictions
+ * const config: DensityGenerationConfig = {
+ *   targetDensity: 2.0,
+ *   maxGridType: 'straight_16th',
+ *   bpmBasedQuantization: true,  // At 80 BPM, this restricts to 8ths
+ *   restrictBpm: 70              // Custom threshold (default: 70)
+ * };
+ * ```
+ */
+export interface DensityGenerationConfig {
+    /** Target density in notes per second */
+    targetDensity: number;
+    /** Maximum quantization grid allowed (independent of density) */
+    maxGridType: ExtendedGridType;
+    /**
+     * When true, apply BPM-based restrictions on top of maxGridType.
+     * Uses medium's thresholds (default: 70 BPM):
+     *   - At BPM >= restrictBpm: straight_16th and triplet_8th restricted to straight_8th
+     * When false, only maxGridType is enforced regardless of BPM.
+     * Default: false
+     */
+    bpmBasedQuantization?: boolean;
+    /** BPM threshold for restricting 16th/triplet_8th to 8ths. Default: 70 (MEDIUM_RESTRICT_BPM) */
+    restrictBpm?: number;
+    /** BPM threshold for restricting 8ths to quarter notes. Default: 120 (EASY_QUARTER_NOTE_BPM) */
+    quarterNoteBpm?: number;
+}
+/**
+ * Maximum subdivision type
+ */
+export type MaxSubdivision = 'eighth' | 'sixteenth';
+/**
+ * Configuration for subdivision limits at a difficulty level
+ */
+export interface SubdivisionLimitConfig {
+    /** Maximum subdivision allowed at this difficulty */
+    maxSubdivision: MaxSubdivision;
+    /** Grid types allowed at this difficulty */
+    allowedGridTypes: ExtendedGridType[];
+    /** Human-readable description of the limits */
+    description: string;
+    /** Target density range for this difficulty (notes per second, BPM-adjusted) */
+    targetDensityRange: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Type of edit applied to create a difficulty variant
+ */
+export type EditType = 'none' | 'simplified' | 'interpolated' | 'pattern_inserted';
+/**
+ * A beat in a difficulty variant that may have been converted to an extended grid type
+ *
+ * This extends CompositeBeat to support Easy difficulty grid types (straight_8th, quarter_triplet)
+ * that aren't in the original GridType.
+ */
+export interface VariantBeat extends Omit<CompositeBeat, 'gridType'> {
+    /** Grid type - extended to support simplified subdivisions */
+    gridType: ExtendedGridType;
+}
+/**
+ * A difficulty variant of the composite stream
+ */
+export interface DifficultyVariant {
+    /** The difficulty level of this variant */
+    difficulty: DifficultyLevel;
+    /** The beats in this variant (may include converted grid types) */
+    beats: VariantBeat[];
+    /** Whether this variant is unedited from the composite */
+    isUnedited: boolean;
+    /** Type of edit applied (if any) */
+    editType: EditType;
+    /** How much was changed (0 = no changes, 1 = heavily modified) */
+    editAmount: number;
+    /** IDs of patterns inserted (if editType is 'pattern_inserted') */
+    patternsInserted?: string[];
+    /** Metadata about subdivision conversions */
+    conversionMetadata?: SubdivisionConversionMetadata;
+    /** Metadata about density enhancement */
+    enhancementMetadata?: EnhancementMetadata;
+    /** Task 4.2.3: Density validation result for downstream consumers */
+    densityValidation?: VariantDensityValidationResult;
+    /** Whether density was clamped due to grid constraints (density-based generation only) */
+    densityClamped?: boolean;
+}
+/**
+ * Metadata about subdivision conversions during simplification
+ */
+export interface SubdivisionConversionMetadata {
+    /** Number of beats converted from 16th to 8th */
+    sixteenthToEighth: number;
+    /** Number of beats converted from 8th triplet to quarter triplet */
+    tripletToQuarterTriplet: number;
+    /** Number of beats converted from 8th to quarter note (straight_8th → straight_4th) */
+    eighthToQuarter: number;
+    /** Number of beats that were removed entirely */
+    beatsRemoved: number;
+    /** Total beats before conversion */
+    totalBeatsBefore: number;
+    /** Total beats after conversion */
+    totalBeatsAfter: number;
+    /** Number of reduction passes used to reach target density */
+    reductionPasses?: number;
+}
+/**
+ * Metadata about density enhancement during variant generation
+ */
+export interface EnhancementMetadata {
+    /** Total beats before enhancement */
+    totalBeatsBefore: number;
+    /** Total beats after enhancement */
+    totalBeatsAfter: number;
+    /** Number of beats added via pattern insertion */
+    patternsInserted: number;
+    /** Number of beats added via grid interpolation */
+    interpolatedBeats: number;
+    /** IDs of patterns that were inserted */
+    insertedPatternIds: string[];
+}
+/**
+ * Result of validating a variant against subdivision limits
+ */
+export interface SubdivisionValidationResult {
+    /** Whether the variant passes validation */
+    isValid: boolean;
+    /** Beats that violate the subdivision limits */
+    violations: SubdivisionViolation[];
+    /** Total number of beats checked */
+    totalBeats: number;
+    /** Number of violating beats */
+    violationCount: number;
+}
+/**
+ * A single subdivision violation
+ */
+export interface SubdivisionViolation {
+    /** The beat that violates the limits */
+    beat: VariantBeat;
+    /** The grid type that is not allowed */
+    gridType: ExtendedGridType;
+    /** Suggested conversion target */
+    suggestedConversion: ExtendedGridType;
+}
+/**
+ * Result of locking grid types per beat index
+ *
+ * This is the foundational structure for the density balancing refactor.
+ * Before any density work, the grid type for each beat index is locked
+ * so all subsequent operations know which grid to use.
+ */
+export interface GridLockResult {
+    /** Beats after resolving mixed grids (single grid per beat index) */
+    beats: CompositeBeat[];
+    /** Map from beat index to locked grid type */
+    gridLock: Map<number, ExtendedGridType>;
+}
+/**
+ * Strategy for where to target within the density range
+ *
+ * - 'midpoint': Aim for the middle of the range (default)
+ * - 'lower': Aim closer to the minimum (more conservative)
+ * - 'upper': Aim closer to the maximum (more aggressive)
+ */
+export type DensityTargetStrategy = 'midpoint' | 'lower' | 'upper';
+/**
+ * Result of calculating beat count targets for a difficulty
+ */
+export interface BeatCountTarget {
+    /** Target beat count to aim for (based on strategy) */
+    targetCount: number;
+    /** Maximum beat count allowed (upper bound of density range) */
+    maxCount: number;
+    /** Minimum beat count allowed (lower bound of density range) */
+    minCount: number;
+    /** The target density value (notes per second) used for calculation */
+    targetDensity: number;
+}
+/**
+ * Result of calculating how many beats to add for enhancement
+ */
+export interface BeatsToAddResult {
+    /** Number of beats to add to reach target */
+    beatsToAdd: number;
+    /** Target beat count to aim for */
+    targetCount: number;
+    /** Maximum beats per index based on allowed grid types */
+    maxBeatsPerIndex: number;
+}
+/**
+ * Result of validating variant density against target range
+ *
+ * Task 4.1: Created for convergence validation
+ */
+export interface VariantDensityValidationResult {
+    /** Whether the variant's density is within the target range */
+    inRange: boolean;
+    /** The calculated density (notes per second) */
+    density: number;
+    /** The target density range for this difficulty */
+    targetRange: {
+        min: number;
+        max: number;
+    };
+    /** The difficulty level that was validated */
+    difficulty: DifficultyLevel;
+}
+/**
+ * Configuration for difficulty variant generation
+ */
+export interface DifficultyVariantConfig {
+    /** Whether to log subdivision conversions for debugging. Default: false */
+    logConversions: boolean;
+    /** Whether to preserve phrase boundaries when simplifying. Default: true */
+    preservePhraseBoundaries: boolean;
+    /** Minimum intensity threshold for keeping beats during simplification. Default: 0.3 */
+    simplificationIntensityThreshold: number;
+    /** Intensity threshold for keeping beats during HEAVY simplification. Default: 0.5 */
+    heavySimplificationIntensityThreshold: number;
+    /** Intensity threshold for removing offbeat 16ths during moderate simplification (hard→medium). Default: 0.4 */
+    moderateSimplificationIntensityThreshold: number;
+    /** Minimum intensity threshold for removing beats during density reduction. Default: 0.25 */
+    densityReductionMinIntensity: number;
+    /** Intensity for interpolated beats (0.0 - 1.0). Default: 0.5 */
+    interpolatedBeatIntensity: number;
+    /** Whether to prefer pattern insertion over simple interpolation. Default: true */
+    preferPatternInsertion: boolean;
+    /** Maximum phrase size to consider for pattern insertion (in beats). Default: 4 */
+    maxPatternInsertionSize: number;
+    /** Strategy for where to target within the density range. Default: 'midpoint' */
+    densityTargetStrategy: DensityTargetStrategy;
+    /** Maximum number of passes for density reduction with progressively relaxed protections. Default: 3 */
+    maxReductionPasses: number;
+    /** Seed for deterministic probability rolls in beat enhancement. If not provided, falls back to a hash of beat data. */
+    seed?: string;
+    /**
+     * Rhythmic balance configuration for density reduction awareness.
+     * When provided, the density reduction will use the strongBeatEmphasis setting
+     * to determine which beats are structurally important.
+     *
+     * This config is passed from RhythmGenerator to ensure density reduction
+     * respects the same rhythmic taste rules as the RhythmicBalancer.
+     */
+    rhythmicBalanceConfig?: RhythmicBalanceConfig;
+}
+/**
+ * Check if a grid type is allowed for a given difficulty at a given BPM.
+ *
+ * @param gridType - The grid type to check
+ * @param difficulty - The difficulty level
+ * @param bpm - Optional BPM. When omitted, uses static SUBDIVISION_LIMITS (no tempo restrictions).
+ * @returns True if the grid type is allowed
+ */
+export declare function isGridTypeAllowed(gridType: GridType, difficulty: DifficultyLevel, bpm?: number): boolean;
+/**
+ * Get the allowed grid types for a difficulty level at a given BPM.
+ *
+ * @param difficulty - The difficulty level
+ * @param bpm - Optional BPM. When omitted, uses static SUBDIVISION_LIMITS (no tempo restrictions).
+ * @returns Array of allowed grid types
+ */
+export declare function getAllowedGridTypes(difficulty: DifficultyLevel, bpm?: number): ExtendedGridType[];
+/**
+ * Convert a grid type to the closest allowed type for a difficulty at a given BPM.
+ *
+ * Conversion rules (when grid type is not already allowed):
+ *
+ * - `straight_16th` → `straight_8th` (or `straight_4th` for Easy at BPM > 120)
+ * - `triplet_8th` → `quarter_triplet`
+ * - `straight_8th` → `straight_4th` (Easy at BPM > 120 only)
+ *
+ * @param gridType - The original grid type (can be extended type)
+ * @param difficulty - The target difficulty
+ * @param bpm - Optional BPM. When omitted, uses static SUBDIVISION_LIMITS.
+ * @param allowedGridTypesOverride - Optional override for allowed grid types (for density-based generation)
+ * @returns The converted grid type (or original if already allowed)
+ */
+export declare function convertToAllowedGridType(gridType: ExtendedGridType, difficulty: DifficultyLevel, bpm?: number, allowedGridTypesOverride?: ExtendedGridType[]): ExtendedGridType;
+/**
+ * Map natural difficulty to difficulty level
+ *
+ * @param naturalDifficulty - The natural difficulty from density analysis
+ * @returns The corresponding difficulty level
+ */
+export declare function naturalDifficultyToLevel(naturalDifficulty: NaturalDifficulty): DifficultyLevel;
+/**
+ * Validate a list of beats against subdivision limits for a difficulty at a given BPM.
+ *
+ * @param beats - The beats to validate (may include extended grid types)
+ * @param difficulty - The difficulty level to validate against
+ * @param bpm - Optional BPM. When omitted, uses static SUBDIVISION_LIMITS.
+ * @returns Validation result with any violations
+ */
+export declare function validateSubdivisionLimits(beats: VariantBeat[], difficulty: DifficultyLevel, bpm?: number): SubdivisionValidationResult;
+/**
+ * Generates difficulty variants from a composite stream
+ *
+ * ## Algorithm Overview
+ *
+ * 1. **Determine Variants to Generate**: Based on the composite's natural difficulty,
+ *    determine which variants need editing vs. remain unedited.
+ *
+ * 2. **Simplification** (for dense composites needing easier difficulties):
+ *    - Enforce subdivision limits (primary constraint for Easy)
+ *    - Prioritize keeping transients on strong beats (1, 3)
+ *    - Remove offbeat subdivisions first
+ *    - Snap removed subdivisions to nearest allowed grid
+ *
+ * 3. **Density Enhancement** (for sparse composites needing harder difficulties):
+ *    - First priority: Insert detected patterns from phrase library
+ *    - Fallback: Simple grid interpolation
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const generator = new DifficultyVariantGenerator();
+ * const variants = generator.generate(composite, phraseAnalysis);
+ *
+ * // Access each variant
+ * const easyVariant = variants.easy;
+ * const mediumVariant = variants.medium;
+ * const hardVariant = variants.hard;
+ *
+ * // Check if a variant was edited
+ * console.log('Easy was simplified:', easyVariant.editType === 'simplified');
+ * console.log('Medium is unedited:', mediumVariant.isUnedited);
+ * ```
+ */
+export declare class DifficultyVariantGenerator {
+    private config;
+    /**
+     * Current unifiedBeatMap for time-signature-aware strong beat detection.
+     * Set during generate() and used by isStrongBeat().
+     */
+    private currentUnifiedBeatMap;
+    constructor(config?: Partial<DifficultyVariantConfig>);
+    /**
+     * Lock grid type per beat index before density work
+     *
+     * This is the foundational method for the density balancing refactor.
+     * Before any density work (simplification or enhancement), lock the grid
+     * type for each beat index so all subsequent operations know which grid to use.
+     *
+     * The method:
+     * 1. Runs `enforceSingleGridPerBeat()` to resolve any mixed grids
+     * 2. Builds a map of beatIndex → dominantGridType from resolved beats
+     * 3. For empty beat indices, resolves grid type from:
+     *    - gridDecisions map (if available)
+     *    - Nearest-neighbor fallback (offsets 1, -1, 2, -2, 3, -3)
+     *    - Default to allowed grid type for target difficulty
+     *
+     * @param beats - Input beats (may have mixed grids)
+     * @param targetDifficulty - Target difficulty level for default grid type
+     * @param bpm - BPM for tempo-aware grid type defaults
+     * @param gridDecisions - Optional grid decisions from quantized streams
+     * @param allowedGridTypes - Optional override for allowed grid types (bypasses getTempoAwareAllowedGridTypes)
+     * @returns Grid lock result with cleaned beats and locked grid map
+     */
+    lockGridPerBeatIndex(beats: CompositeBeat[], targetDifficulty: DifficultyLevel, bpm: number, gridDecisions?: Map<number, GridDecision>, allowedGridTypes?: ExtendedGridType[]): GridLockResult;
+    /**
+     * Generate all three difficulty variants from a composite stream
+     *
+     * After generation, each variant is validated against its subdivision limits
+     * to ensure compliance.
+     *
+     * @param composite - The composite stream from CompositeStreamGenerator
+     * @param phraseAnalysis - Optional phrase analysis for pattern library access
+     * @param gridDecisions - Optional grid decisions from quantized streams
+     * @returns Object containing easy, medium, and hard variants
+     */
+    generate(composite: CompositeStream, unifiedBeatMap: UnifiedBeatMap, phraseAnalysis?: PhraseAnalysisResult, gridDecisions?: Map<number, GridDecision>): {
+        easy: DifficultyVariant;
+        medium: DifficultyVariant;
+        hard: DifficultyVariant;
+        natural: DifficultyVariant;
+    };
+    /**
+     * Generate a custom difficulty variant at a specific target density.
+     *
+     * This method provides granular control over difficulty generation by decoupling
+     * target density (notes/second) from maximum quantization grid. Unlike the preset
+     * difficulties (easy/medium/hard/natural), this allows any combination such as:
+     * - Dense chart (3.0 nps) with only 8th note quantization
+     * - Sparse chart (0.5 nps) with 16th note quantization allowed
+     *
+     * The method handles three scenarios:
+     * 1. **Current density > target**: Simplify beats (remove/convert notes)
+     * 2. **Current density < target**: Enhance beats (add notes via interpolation/patterns)
+     * 3. **Current density ≈ target**: Apply grid restrictions only if needed
+     *
+     * Best-effort: If the target density is impossible given the grid constraints
+     * (e.g., 4.0 nps with only 8th notes at 60 BPM), the density is clamped to the
+     * maximum achievable and a warning is logged.
+     *
+     * @param composite - The composite stream from CompositeStreamGenerator
+     * @param config - Density generation configuration (target density + max grid type)
+     * @param unifiedBeatMap - The unified beat map for timing information
+     * @param phraseAnalysis - Optional phrase analysis for pattern library access during enhancement
+     * @param gridDecisions - Optional grid decisions from quantized streams
+     * @returns A DifficultyVariant with `difficulty: 'custom'`
+     *
+     * @example
+     * ```typescript
+     * const generator = new DifficultyVariantGenerator();
+     *
+     * // Dense chart with 8th note max grid
+     * const denseVariant = generator.generateAtDensity(
+     *     composite,
+     *     { targetDensity: 3.0, maxGridType: 'straight_8th' },
+     *     unifiedBeatMap
+     * );
+     *
+     * // Sparse chart with 16th note grid allowed, BPM-based restrictions
+     * const sparseVariant = generator.generateAtDensity(
+     *     composite,
+     *     { targetDensity: 0.5, maxGridType: 'straight_16th', bpmBasedQuantization: true },
+     *     unifiedBeatMap
+     * );
+     * ```
+     */
+    generateAtDensity(composite: CompositeStream, config: DensityGenerationConfig, unifiedBeatMap: UnifiedBeatMap, phraseAnalysis?: PhraseAnalysisResult, gridDecisions?: Map<number, GridDecision>): DifficultyVariant;
+    /**
+     * Generate multiple custom difficulty variants at specific densities in one call
+     *
+     * This is a convenience method for generating multiple density-based variants
+     * efficiently. Each variant is generated independently with its own deep copy
+     * of the composite beats, ensuring no shared state or mutations between variants.
+     *
+     * @param composite - The composite stream from CompositeStreamGenerator
+     * @param configs - Array of labeled density configurations
+     * @param unifiedBeatMap - The unified beat map for timing information
+     * @param phraseAnalysis - Optional phrase analysis for pattern library access during enhancement
+     * @param gridDecisions - Optional grid decisions from quantized streams
+     * @returns A Map of labels to DifficultyVariants
+     *
+     * @example
+     * ```typescript
+     * const generator = new DifficultyVariantGenerator();
+     *
+     * const variants = generator.generateAtDensities(
+     *     composite,
+     *     [
+     *         { label: 'beginner', config: { targetDensity: 0.5, maxGridType: 'straight_4th' } },
+     *         { label: 'intermediate', config: { targetDensity: 1.5, maxGridType: 'straight_8th' } },
+     *         { label: 'expert', config: { targetDensity: 3.0, maxGridType: 'straight_16th' } },
+     *     ],
+     *     unifiedBeatMap
+     * );
+     *
+     * const beginnerVariant = variants.get('beginner');
+     * const expertVariant = variants.get('expert');
+     * ```
+     */
+    generateAtDensities(composite: CompositeStream, configs: {
+        label: string;
+        config: DensityGenerationConfig;
+    }[], unifiedBeatMap: UnifiedBeatMap, phraseAnalysis?: PhraseAnalysisResult, gridDecisions?: Map<number, GridDecision>): Map<string, DifficultyVariant>;
+    /**
+     * Validate a generated variant against its subdivision limits
+     *
+     * This ensures that all generated variants comply with their respective
+     * difficulty's subdivision constraints. Logs warnings if violations are found.
+     *
+     * @param variant - The variant to validate
+     * @param difficulty - The difficulty level
+     */
+    private validateVariant;
+    /**
+     * Validate that a variant's beats have no mixed grid types per beat index
+     *
+     * Task 1.4.3: Validation-only check for grid lock compliance.
+     * When grid lock is used in generateVariant(), this method confirms
+     * that no grid violations exist (assert, don't fix).
+     *
+     * @param beats - The beats to validate
+     * @param difficulty - The difficulty level for logging
+     */
+    private validateGridLockResult;
+    /**
+     * Validate that a variant's density falls within the target range for its difficulty
+     *
+     * Task 4.1: Convergence validation - check final density against target range
+     *
+     * This method calculates the final density of a variant and compares it against
+     * the target density range defined in SUBDIVISION_LIMITS. It logs warnings for
+     * out-of-range variants but does NOT throw, since edge cases (very short songs,
+     * extreme tempos) may not be able to hit exact targets.
+     *
+     * @param variant - The variant to validate
+     * @param bpm - The tempo in beats per minute
+     * @returns DensityValidationResult with inRange status, density, and target range
+     */
+    private validateDensityInRange;
+    /**
+     * Generate a single difficulty variant
+     *
+     * @param targetDifficulty - The target difficulty level
+     * @param composite - The composite stream
+     * @param naturalDifficulty - The natural difficulty of the composite
+     * @param phraseAnalysis - Optional phrase analysis for pattern library access
+     * @param gridDecisions - Optional grid decisions from quantized streams
+     * @returns The difficulty variant
+     */
+    private generateVariant;
+    /**
+     * Simplify beats to meet subdivision limits for a target difficulty
+     *
+     * This method converts beats that violate subdivision limits to allowed grid types:
+     * - `straight_16th` → `straight_8th` (snap 16th notes to nearest 8th note)
+     * - `triplet_8th` → `quarter_triplet` (snap 8th triplets to quarter note triplet)
+     *
+     * For heavy simplification (hard -> easy), additional beat prioritization is applied:
+     * - Prioritize keeping transients on strong beats (beats 1 and 3 of each measure)
+     * - Remove offbeat subdivisions first (gridPosition 1 and 3)
+     * - Keep only core beats (high intensity or on strong beats)
+     *
+     * After conversion, duplicate beats at the same grid position are deduplicated
+     * (keeping the highest intensity).
+     *
+     * @param beats - The beats to simplify
+     * @param targetDifficulty - The target difficulty level
+     * @param quarterNoteInterval - Duration of a quarter note in seconds for timestamp calculation
+     * @param isHeavySimplification - Whether this is heavy simplification (hard -> easy)
+     * @param phraseAnalysis - Optional phrase analysis for preserving phrase boundaries
+     * @returns Simplified beats with conversion metadata
+     */
+    private simplifyBeats;
+    /**
+     * Filter beats for heavy simplification (hard -> easy)
+     *
+     * Implements beat prioritization:
+     * 1. Strong beats (beats 1 and 3 of each measure) are always kept
+     * 2. Downbeats (gridPosition 0) on weak beats are kept if high intensity
+     * 3. Offbeats (gridPosition 1, 2, 3) are only kept if very high intensity
+     * 4. Beats part of significant phrases get additional consideration
+     *
+     * In 4/4 time with 0-indexed beats:
+     * - Beat 0, 4, 8... = Beat 1 of measure (strong)
+     * - Beat 2, 6, 10... = Beat 3 of measure (strong)
+     * - Beat 1, 5, 9... = Beat 2 of measure (weak)
+     * - Beat 3, 7, 11... = Beat 4 of measure (weak)
+     *
+     * @param beats - The beats to filter
+     * @param metadata - Metadata object to track removals
+     * @param phraseMembership - Map of beat indices to phrase membership
+     * @returns Filtered beats
+     */
+    private filterBeatsForHeavySimplification;
+    /**
+     * Determine if a beat index is on a strong beat, based on time signature and emphasis mode
+     *
+     * This method uses the rhythmicBalanceConfig.strongBeatEmphasis to determine
+     * which beats are "strong" for density reduction priority. It is
+     * time-signature-aware: derives beatsPerMeasure from the active downbeat segment.
+     *
+     * @param beatIndex - The beat index (0-indexed)
+     * @returns True if this is a strong beat
+     */
+    private isStrongBeat;
+    /**
+     * Calculate the density (notes per second) of a beat collection
+     *
+     * Uses `maxBeatIndex + 1` as the denominator to match DensityAnalyzer's method,
+     * Uses the actual track duration in seconds to compute true notes-per-second.
+     *
+     * @param beats - The beats to analyze
+     * @param durationSeconds - Actual track duration in seconds (from unifiedBeatMap.duration)
+     * @returns Notes per second (0 if no beats or no duration)
+     */
+    private calculateDensity;
+    /**
+     * Calculate target beat count for a difficulty level based on density ranges
+     *
+     * This is the foundational helper for global target-based density control.
+     * It calculates exactly how many beats should be in the output based on:
+     * - The target density range for the difficulty
+     * - The total quarter-note span of the song
+     * - The BPM
+     * - The configured strategy (midpoint/lower/upper)
+     *
+     * Target densities by difficulty:
+     * - Easy: 0.9 nps (biased high within [0, 1.0] to preserve musical interest)
+     * - Medium: 1.25 nps (true center of [1.0, 1.5])
+     * - Hard: 1.75 nps (target above the 1.5 floor)
+     * - Natural: Uses the current density (no target)
+     *
+     * The formula derives from: density = (beatCount / totalQuarterNotes) * (bpm / 60)
+     * Solving for beatCount: beatCount = density * totalQuarterNotes * 60 / bpm
+     *
+     * @param currentBeatCount - The current number of beats
+     * @param totalQuarterNotes - The total quarter-note span (maxBeatIndex + 1)
+     * @param bpm - Tempo in beats per minute
+     * @param targetDifficulty - The target difficulty level
+     * @returns Beat count target with min/max bounds
+     */
+    private calculateBeatCountTarget;
+    /**
+     * Calculate how many beats to add for density enhancement
+     *
+     * This method calculates the exact number of beats to add to reach the target
+     * density for a given difficulty level. It uses the same target density midpoints
+     * as calculateBeatCountTarget() for consistency.
+     *
+     * Task 3.1: Global target-based density enhancement helper
+     *
+     * @param currentBeatCount - Current number of beats
+     * @param durationSeconds - Actual track duration in seconds
+     * @param bpm - Beats per minute
+     * @param targetDifficulty - Target difficulty level
+     * @returns BeatsToAddResult with beatsToAdd, targetCount, and maxBeatsPerIndex
+     */
+    private calculateBeatsToAdd;
+    /**
+     * Get max beats per index from a set of allowed grid types
+     *
+     * Returns the maximum number of beats that can fit at a single beat index
+     * based on the most complex grid type in the allowed set.
+     *
+     * @param allowedTypes - Array of allowed grid types
+     * @returns Maximum beats per index
+     */
+    private getMaxBeatsPerIndexFromGridTypes;
+    /**
+     * Get max beats for a single grid type
+     *
+     * @param gridType - The grid type
+     * @returns Maximum beats per index for this grid type
+     */
+    private getMaxBeatsForGridType;
+    /**
+     * Distribute beats across indices to reach a global target count
+     *
+     * Uses deterministic global target-based distribution.
+     *
+     * Strategy:
+     * - Phase A: Fill empty indices first (prioritize gaps in rhythm)
+     * - Phase B: Fill partially occupied indices (add to existing beats)
+     *
+     * The distribution is deterministic and greedy. Empty indices are always prioritized.
+     * Seed is only used for tiebreaking when multiple indices are equally good candidates.
+     *
+     * @param beatsToAdd - Global count of beats to add
+     * @param beatsByIndex - Current beat occupancy per index
+     * @param gridLock - Per-index grid types (from lockGridPerBeatIndex)
+     * @param maxBeatIndex - The highest beat index in the song
+     * @param seed - Seed for deterministic tiebreaking
+     * @returns Map of beatIndex → targetCount (how many beats should be at each index after distribution)
+     */
+    private distributeBeatsAcrossIndices;
+    /**
+     * Group consecutive empty indices into gaps
+     *
+     * @param emptyIndices - Array of empty beat indices (sorted)
+     * @returns Array of gap arrays, each containing consecutive empty indices
+     */
+    private groupConsecutiveEmptyIndices;
+    /**
+     * Reduce density by removing low-priority beats until target is reached
+     *
+     * This method implements a priority-based beat removal strategy:
+     * 1. Calculate current density
+     * 2. If above target, sort beats by removal priority (lowest priority first)
+     * 3. Remove beats one at a time until density is within target range
+     *
+     * Removal priority (lowest to highest - low priority = removed first):
+     * - Offbeats (gridPosition 1, 3) with low intensity - removed first
+     * - Mid-beat positions (gridPosition 2) with low intensity
+     * - Downbeats (gridPosition 0) on weak beats (2, 4 of measure)
+     * - Strong beats (beats 1, 3 of measure) - kept as long as possible
+     *
+     * Protected beats (not removed):
+     * - Pass 1: Beats with priority >= (1 - densityReductionMinIntensity) or intensity >= moderateSimplificationIntensityThreshold
+     * - Pass 2: Relaxed thresholds (priority threshold lowered by 0.15, intensity threshold lowered by 0.1)
+     * - Pass 3+: Only strong beats (beatIndex % 4 === 0 or 2) are protected
+     *
+     * @param beats - The beats to potentially reduce
+     * @param targetDifficulty - The target difficulty level
+     * @param metadata - Metadata to track removals
+     * @param phraseMembership - Map of beat indices to phrase membership
+     * @returns Beats with density reduced to target range
+     */
+    private reduceDensityToTarget;
+    /**
+     * Build a map of measureNumber → count of downbeats (gridPosition === 0) in that measure.
+     *
+     * Uses unifiedBeatMap to resolve measureNumber from beatIndex, supporting any time signature.
+     *
+     * @param beats - The beats to scan
+     * @returns Map from measureNumber to downbeat count
+     */
+    private buildDownbeatCountMap;
+    /**
+     * Calculate removal priority for a beat (higher = more important to keep)
+     *
+     * Priority factors:
+     * - Strong beat bonus: +0.3 (zeroed in 'neutral' mode)
+     * - Downbeat bonus: +0.2 (gridPosition 0)
+     * - Only-downbeat-in-measure bonus: +0.2 (stacks on downbeat bonus)
+     * - Intensity contribution: +intensity * 0.3
+     * - Phrase membership bonus: +0.15 (max)
+     * - Offbeat penalty: -0.1 (gridPosition 1 or 3)
+     *
+     * @param beat - The beat to evaluate
+     * @param phraseMembership - Map of beat indices to phrase membership
+     * @param downbeatCountByMeasure - Map of measureNumber → downbeat count for structural importance
+     * @returns Priority score (0-1 range, higher = keep)
+     */
+    private calculateRemovalPriority;
+    /**
+     * Convert a single beat to an allowed grid type
+     *
+     * Conversion rules for Easy difficulty:
+     * - `straight_16th` (4 positions: 0, 1, 2, 3) → `straight_8th` (2 positions: 0, 2)
+     *   - Position 0 → 0 (quarter note)
+     *   - Position 1 → 0 (snaps back to quarter)
+     *   - Position 2 → 2 (8th note)
+     *   - Position 3 → 2 (snaps to 8th)
+     *
+     * - `triplet_8th` (3 positions: 0, 1, 2) → `quarter_triplet` (1 position: 0)
+     *   - All positions snap to 0 (quarter triplet)
+     *
+     * - `straight_8th` (2 positions: 0, 1) → `straight_4th` (1 position: 0)
+     *   - All positions snap to 0 (quarter note) — Easy at BPM > 120
+     *
+     * - `straight_16th` → `straight_4th` (Easy at BPM > 120)
+     *   - All positions snap to 0 (quarter note)
+     *
+     * @param beat - The beat to convert
+     * @param targetDifficulty - The target difficulty
+     * @param quarterNoteInterval - Duration of a quarter note in seconds
+     * @param bpm - The tempo in BPM (for tempo-aware grid type selection)
+     * @returns The converted beat as VariantBeat, or null if the beat should be removed
+     */
+    private convertBeatGridType;
+    /**
+     * Deduplicate converted beats that may have snapped to the same grid position
+     *
+     * After conversion, multiple beats may end up at the same (beatIndex, gridPosition, gridType).
+     * This method keeps only the highest-intensity beat at each position.
+     *
+     * @param beats - Converted beats (may have duplicates)
+     * @returns Deduplicated beats
+     */
+    private deduplicateConvertedBeats;
+    /**
+     * Determine if simplification is needed
+     *
+     * @param targetDifficulty - The target difficulty
+     * @param naturalDifficulty - The natural difficulty of the composite
+     * @returns True if simplification is needed
+     */
+    private needsSimplification;
+    /**
+     * Determine if enhancement is needed
+     *
+     * @param targetDifficulty - The target difficulty
+     * @param naturalDifficulty - The natural difficulty of the composite
+     * @returns True if enhancement is needed
+     */
+    private needsEnhancement;
+    /**
+     * Determine if this is heavy simplification (2 levels down)
+     *
+     * Heavy simplification occurs when going from hard -> easy (skipping medium).
+     * This requires more aggressive beat removal - keeping only core beats.
+     *
+     * @param targetDifficulty - The target difficulty
+     * @param naturalDifficulty - The natural difficulty of the composite
+     * @returns True if this is heavy simplification
+     */
+    private isHeavySimplification;
+    /**
+     * Enhance beats by adding density through pattern insertion and interpolation
+     *
+     * ## Algorithm Overview
+     *
+     * 1. **Pattern Insertion** (first priority):
+     *    - Look for suitable patterns from the phrase library
+     *    - Insert patterns at beats that have low density
+     *    - Patterns are song-specific and more interesting than simple interpolation
+     *
+     * 2. **Grid Interpolation** (fallback):
+     *    - For beats where no pattern matches, interpolate additional subdivisions
+     *    - Respect per-beat grid decisions (16th vs triplet) from Phase 1
+     *    - Add beats at intermediate grid positions
+     *
+     * @param beats - The beats to enhance
+     * @param targetDifficulty - The target difficulty level
+     * @param bpm - BPM for calculating global target beat count
+     * @param unifiedBeatMap - The unified beat map for timestamp derivation
+     * @param phraseAnalysis - Optional phrase analysis for pattern library
+     * @param gridDecisions - Optional grid decisions from quantized streams
+     * @param quarterNoteInterval - Duration of a quarter note in seconds for timestamp calculation
+     * @param gridLock - Optional grid lock map (from lockGridPerBeatIndex) - if provided, skips initial enforceSingleGridPerBeat
+     * @returns Enhanced beats with metadata
+     */
+    private enhanceBeats;
+    /**
+     * Group beats by their beat index
+     */
+    private groupBeatsByIndex;
+    /**
+     * Calculate target beats per beat index based on density multiplier
+     *
+     * Includes empty beat indices (those with no existing beats) so that
+     * enhancement can fill gaps in the rhythm. Empty beats get a target
+     * proportional to the multiplier, treating them as having 1 virtual beat.
+     */
+    private calculateTargetBeatsPerBeat;
+    /**
+     * Try to insert a pattern from the phrase library
+     *
+     * Looks for patterns that:
+     * - Have available slots in the current beat
+     * - Match the grid type of existing beats
+     * - Are within the max pattern size limit
+     */
+    private tryInsertPattern;
+    /**
+     * Create beats for an empty beat index (one with no existing beats)
+     *
+     * When enhancement needs to fill gaps in the rhythm, this method creates
+     * beats from scratch using grid decisions or neighbor context to determine
+     * the appropriate grid type and timing.
+     *
+     * @param beatIndex - The beat index to create beats for
+     * @param beatsToAdd - Number of beats to create
+     * @param unifiedBeatMap - Optional unified beat map for timestamp derivation
+     * @param gridDecisions - Optional grid decisions from quantized streams
+     * @param quarterNoteInterval - Duration of a quarter note in seconds
+     * @param beatsByIndex - All beats grouped by index (for neighbor lookup)
+     * @param occupiedSlots - Global occupied slot tracker
+     * @param lockedGridType - Optional locked grid type from gridLock (takes priority over other sources)
+     * @returns Array of newly created beats
+     */
+    private createBeatsForEmptyIndex;
+    /**
+     * Interpolate beats to add density
+     *
+     * Adds beats at intermediate grid positions that don't already have beats.
+     * Always uses the existing beats' grid type to avoid mixed grids.
+     *
+     * @param existingBeats - Existing beats at this beat index
+     * @param beatIndex - The beat index to interpolate for
+     * @param beatsToAdd - Number of beats to add
+     * @param quarterNoteInterval - Duration of a quarter note in seconds for timestamp calculation
+     * @param occupiedSlots - Global occupied slot tracker
+     * @param lockedGridType - Grid type locked for this beat index (ExtendedGridType for full support)
+     * @param unifiedBeatMap - The unified beat map for authoritative timestamp derivation
+     * @returns Array of interpolated beats
+     */
+    private interpolateBeats;
+    /**
+     * Determine the grid type for a beat index.
+     * Used when creating beats for an empty index that has no existing beats.
+     */
+    private getGridForBeatIndex;
+    /**
+     * Deduplicate enhanced beats — each beat index has exactly one grid type.
+     * Beats at the same beatIndex:gridPosition are the same musical event regardless
+     * of grid type. If two grid types somehow landed at the same position, keep the
+     * one matching the dominant grid type for that beat index.
+     */
+    private deduplicateEnhancedBeats;
+    /**
+     * Enforce single grid type per beat index.
+     *
+     * When a beat index has notes from both triplet and straight grids,
+     * keep only the grid type with higher total intensity. This prevents
+     * unmusical combinations like a 16th note and a triplet in the same beat.
+     *
+     * @param beats - The beats to enforce single-grid on
+     * @returns Beats with at most one grid type per beat index
+     */
+    private enforceSingleGridPerBeat;
+    /**
+     * Validate that beats have no mixed grid types per beat index
+     *
+     * Task 1.3.4: Validation-only check for grid lock compliance.
+     * When grid lock is provided to enhanceBeats(), this method confirms
+     * that no grid violations exist (assert, don't fix).
+     *
+     * @param beats - The beats to validate
+     * @returns Validation result with any violations found
+     */
+    private validateSingleGridPerBeat;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): DifficultyVariantConfig;
+    /**
+     * Build a map of beat indices to their phrase membership
+     *
+     * This creates a lookup structure to quickly check if a beat is part of
+     * a detected rhythmic phrase, and how significant that phrase is.
+     *
+     * @param phraseAnalysis - The phrase analysis result
+     * @returns Map from beat index to array of phrases that include that beat
+     */
+    private buildPhraseMembershipMap;
+    /**
+     * Check if a beat should be preserved due to phrase membership
+     *
+     * When preservePhraseBoundaries is enabled, this method determines if
+     * a beat that would normally be removed should be kept because it's
+     * part of a significant detected phrase.
+     *
+     * @param beat - The beat to check
+     * @param phraseMembership - Map of beat indices to phrase membership
+     * @param intensityThreshold - The intensity threshold being used
+     * @returns True if the beat should be preserved due to phrase membership
+     */
+    private shouldPreserveForPhrase;
+}
+//# sourceMappingURL=DifficultyVariantGenerator.d.ts.map