playlist-data-engine 1.1.0

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

@@ -0,0 +1,275 @@
+/**
+ * Stream Scorer for Procedural Rhythm Generation
+ *
+ * Evaluates the "interest" level of each band stream per section.
+ * Used to determine which band has the most interesting rhythm for composite generation.
+ *
+ * Part of the Procedural Rhythm Generation pipeline - Phase 3.1
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - score band streams for interest level
+ * const scorer = new StreamScorer();
+ * const result = scorer.score(quantizedBandStreams, phraseAnalysis, densityAnalysis);
+ *
+ * // Check which band won each section
+ * for (const winner of result.sectionWinners) {
+ *   console.log(`Beats ${winner.beatRange.start}-${winner.beatRange.end}: ${winner.band} won`);
+ * }
+ *
+ * // Compare overall band performance
+ * console.log('Band totals:', result.bandTotals);
+ * console.log('Band averages:', result.bandAverages);
+ *
+ * // Inspect individual scoring factors
+ * for (const score of result.sectionScores) {
+ *   console.log(`${score.band} @ ${score.beatRange.start}: ${score.score.toFixed(2)}`);
+ *   console.log(`  IOI variance: ${score.factors.ioiVariance.toFixed(2)}`);
+ *   console.log(`  Syncopation: ${score.factors.syncopationLevel.toFixed(2)}`);
+ * }
+ * ```
+ */
+import type { QuantizedBandStreams } from './RhythmQuantizer.js';
+import type { PhraseAnalysisResult } from './PhraseAnalyzer.js';
+import type { DensityAnalysisResult } from './DensityAnalyzer.js';
+import type { ControllerMode } from '../../types/ButtonMapping.js';
+/**
+ * Band identifier
+ */
+export type Band = 'low' | 'mid' | 'high';
+/**
+ * Scoring factors that contribute to the overall interest score
+ */
+export interface ScoringFactors {
+    /** Inter-Onset Interval variance (rhythmic variety) */
+    ioiVariance: number;
+    /** Syncopation level (offbeat emphasis) */
+    syncopationLevel: number;
+    /** Phrase significance from detected patterns */
+    phraseSignificance: number;
+    /** Density contribution (more notes = more interesting, to a point) */
+    densityFactor: number;
+}
+/**
+ * Score for a single section of a single band
+ */
+export interface SectionScore {
+    /** Beat range for this section */
+    beatRange: {
+        start: number;
+        end: number;
+    };
+    /** Which band this score is for */
+    band: Band;
+    /** Overall interest score (0.0 - 1.0, higher = more interesting) */
+    score: number;
+    /** Individual scoring factors */
+    factors: ScoringFactors;
+}
+/**
+ * Complete scoring result for all bands across all sections
+ */
+export interface StreamScoringResult {
+    /** All section scores */
+    sectionScores: SectionScore[];
+    /** Per-band total scores (sum of all section scores) */
+    bandTotals: {
+        low: number;
+        mid: number;
+        high: number;
+    };
+    /** Per-band average scores */
+    bandAverages: {
+        low: number;
+        mid: number;
+        high: number;
+    };
+    /** For each section, which band won (highest score) */
+    sectionWinners: SectionWinner[];
+    /** Configuration used for scoring */
+    config: StreamScorerConfig;
+}
+/**
+ * Winner for a section
+ */
+export interface SectionWinner {
+    /** Beat range for this section */
+    beatRange: {
+        start: number;
+        end: number;
+    };
+    /** Which band won this section */
+    winner: Band;
+    /** The winning score */
+    score: number;
+    /** Margin of victory over second place */
+    margin: number;
+}
+/**
+ * Band bias weights for controlling which frequency bands are favored
+ * in composite stream selection.
+ *
+ * Values are applied as multipliers to the final score:
+ * - 1.0 = no bias (neutral)
+ * - > 1.0 = favor this band
+ * - < 1.0 = disfavor this band
+ *
+ * Example: To reduce bass dominance, set { low: 0.5, mid: 1.0, high: 1.0 }
+ */
+export interface BandBiasWeights {
+    low: number;
+    mid: number;
+    high: number;
+}
+/**
+ * Configuration for stream scoring
+ */
+export interface StreamScorerConfig {
+    /** Number of beats per section for scoring. Default: 8 (2 measures in 4/4 time) */
+    beatsPerSection: number;
+    /** Weight for IOI variance in scoring. Default: 0.3 */
+    ioiVarianceWeight: number;
+    /** Weight for syncopation in scoring. Default: 0.3 */
+    syncopationWeight: number;
+    /** Weight for phrase significance in scoring. Default: 0.25 */
+    phraseSignificanceWeight: number;
+    /** Weight for density factor in scoring. Default: 0.15 */
+    densityWeight: number;
+    /** Grid positions considered "offbeats" for syncopation scoring.
+     *  For straight_16th: 1 and 3 are offbeats (16th note subdivisions)
+     *  For triplet_8th: 1 and 2 are offbeats (after the downbeat)
+     *  For straight_8th: 1 is offbeat (the "and" in "1-and")
+     */
+    offbeatGridPositions: {
+        straight_16th: number[];
+        triplet_8th: number[];
+        straight_8th: number[];
+    };
+    /** Band bias multipliers applied to final section scores.
+     *  undefined = no bias (default)
+     *  Range: 0.0 - 2.0 (0 = never win, 1 = neutral, 2 = strongly favored)
+     */
+    bandBiasWeights?: BandBiasWeights;
+    /** BPM for tempo-aware density factor calculation.
+     *  When provided, density is measured in notes/second (BPM-adjusted).
+     *  When undefined, density falls back to notes/beat (legacy behavior).
+     *  Default: undefined
+     */
+    bpm?: number;
+}
+/**
+ * Get the default scoring factor weights for a controller mode.
+ *
+ * Returns the mode-specific defaults for the 4 scoring factors (ioiVarianceWeight,
+ * syncopationWeight, phraseSignificanceWeight, densityWeight). Band bias weights
+ * are the same across all modes.
+ *
+ * @param controllerMode - The controller mode to get defaults for
+ * @returns Full StreamScorerConfig with mode-specific factor weights
+ */
+export declare function getControllerModeScoringDefaults(controllerMode: ControllerMode): StreamScorerConfig;
+/**
+ * Evaluates the "interest" level of each band stream per section.
+ *
+ * ## Scoring Algorithm
+ *
+ * The scoring system evaluates rhythmic interest based on four factors:
+ *
+ * 1. **IOI Variance** (Inter-Onset Interval): Measures rhythmic variety.
+ *    - Higher variance = more interesting rhythms (not just straight notes)
+ *    - Low variance = monotonous patterns
+ *
+ * 2. **Syncopation Level**: Measures offbeat emphasis.
+ *    - Notes on grid positions 1 or 3 (16th notes) are syncopated
+ *    - Syncopated rhythms are generally more interesting
+ *
+ * 3. **Phrase Significance**: Incorporates detected phrase patterns.
+ *    - Sections containing significant detected phrases score higher
+ *    - Encourages using sections with meaningful musical content
+ *
+ * 4. **Density Factor**: Considers note density.
+ *    - Moderate density is ideal (not too sparse, not too dense)
+ *    - Uses a bell curve centered around an optimal notes/second value (BPM-aware)
+ *    - When BPM is configured, density is measured in notes/second for tempo-accurate scoring
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const scorer = new StreamScorer();
+ * const result = scorer.score(quantizedStreams, phraseAnalysis, densityAnalysis);
+ *
+ * // Get section winners for composite generation
+ * for (const winner of result.sectionWinners) {
+ *   console.log(`Beats ${winner.beatRange.start}-${winner.beatRange.end}: ${winner.winner} wins`);
+ * }
+ *
+ * // Get average scores per band
+ * console.log('Low band avg:', result.bandAverages.low);
+ * console.log('Mid band avg:', result.bandAverages.mid);
+ * console.log('High band avg:', result.bandAverages.high);
+ * ```
+ */
+export declare class StreamScorer {
+    private config;
+    constructor(config?: Partial<StreamScorerConfig>);
+    /**
+     * Score all band streams across all sections
+     *
+     * @param streams - Quantized band streams from RhythmQuantizer
+     * @param phraseAnalysis - Phrase analysis from PhraseAnalyzer
+     * @param densityAnalysis - Density analysis from DensityAnalyzer
+     * @returns Complete scoring result
+     */
+    score(streams: QuantizedBandStreams, phraseAnalysis: PhraseAnalysisResult, densityAnalysis: DensityAnalysisResult): StreamScoringResult;
+    /**
+     * Score a single section of a single band
+     */
+    private scoreSection;
+    /**
+     * Calculate Inter-Onset Interval variance
+     *
+     * Higher variance indicates more rhythmic variety (more interesting).
+     * Normalized to 0-1 range.
+     */
+    private calculateIOIVariance;
+    /**
+     * Calculate syncopation level
+     *
+     * Measures emphasis on offbeats. Higher syncopation = more interesting.
+     * Normalized to 0-1 range.
+     */
+    private calculateSyncopationLevel;
+    /**
+     * Calculate phrase significance for a section
+     *
+     * Higher if significant phrases overlap with this section.
+     * Normalized to 0-1 range.
+     */
+    private calculatePhraseSignificance;
+    /**
+     * Calculate density factor
+     *
+     * Uses a bell curve - moderate density is ideal.
+     * When BPM is configured, density is measured in notes/second for tempo-accurate scoring.
+     * Optimal density is around 1.0 notes/second.
+     * Normalized to 0-1 range.
+     */
+    private calculateDensityFactor;
+    /**
+     * Determine the winner for each section
+     */
+    private determineSectionWinners;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): StreamScorerConfig;
+    /**
+     * Update configuration options.
+     * Merges the provided partial config with the existing config.
+     * Use this to set runtime values like BPM that aren't known at construction time.
+     *
+     * @param partial - Partial config to merge
+     */
+    updateConfig(partial: Partial<StreamScorerConfig>): void;
+}
+//# sourceMappingURL=StreamScorer.d.ts.map

package/dist/core/analysis/beat/StreamScorer.d.ts.map

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

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

@@ -0,0 +1,256 @@
+/**
+ * Tempo-Aware Quantization
+ *
+ * Extensible pipeline step that applies BPM-based rules to constrain the
+ * quantization grid for fundamental playability, independent of difficulty
+ * settings.
+ *
+ * ## Architecture
+ *
+ * The TempoAwareQuantizer plugs into the decide-then-quantize flow:
+ *
+ * ```
+ * decideGrids()           →  RhythmQuantizer base decisions
+ * ↓
+ * TempoAwareQuantizer.applyRules()  →  BPM-constrained decisions
+ * ↓
+ * quantizeToGrids()       →  Quantize from original timestamps to final grid
+ * ```
+ *
+ * Rules are consulted during grid decision-making, not applied post-hoc to
+ * already-quantized data. This means there is only ONE quantization pass.
+ *
+ * @example
+ * ```typescript
+ * const quantizer = new TempoAwareQuantizer({
+ *   enabled: true,
+ *   rules: [new HighBpmGridRestrictionRule()],
+ * });
+ *
+ * // Get base grid decisions from RhythmQuantizer
+ * const baseDecisions = rhythmQuantizer.decideGrids(transients, beatMap, 'mid');
+ *
+ * // Apply BPM-aware rules
+ * const finalDecisions = quantizer.applyRules(baseDecisions, {
+ *   bpm: beatMap.quarterNoteBpm,
+ *   quarterNoteInterval: beatMap.quarterNoteInterval,
+ *   band: 'mid',
+ *   transients,
+ * });
+ * ```
+ */
+import type { GridDecision } from './RhythmQuantizer.js';
+import { RhythmQuantizer } from './RhythmQuantizer.js';
+import type { TransientResult } from './TransientDetector.js';
+import type { UnifiedBeatMap } from '../../types/BeatMap.js';
+/**
+ * Context passed to tempo quantization rules.
+ */
+export interface TempoRuleContext {
+    /** Current BPM from the UnifiedBeatMap */
+    bpm: number;
+    /** Quarter note interval in seconds */
+    quarterNoteInterval: number;
+    /** Frequency band being processed */
+    band: 'low' | 'mid' | 'high';
+    /** Raw transients for this band (original timestamps, not quantized) */
+    transients: TransientResult[];
+}
+/**
+ * A rule that can modify grid decisions based on tempo context.
+ *
+ * Rules are applied in order. Each rule's `apply()` receives the grid
+ * decisions (possibly already modified by earlier rules) and returns
+ * the (possibly modified) decisions.
+ *
+ * When overriding a grid decision, rules should:
+ * - Set `confidence: 1.0` (forced/authoritative)
+ * - Clear `straightAvgOffset` and `tripletAvgOffset`
+ *
+ * This matches the pattern used by `RhythmQuantizer.getBandGridType()` for
+ * forced grid decisions, and ensures that `collectGridDecisions()` in
+ * RhythmGenerator correctly prefers BPM-forced decisions over
+ * lower-confidence auto-detected ones.
+ */
+export interface TempoQuantizationRule {
+    /** Unique identifier for this rule (e.g., 'high-bpm-grid-restriction') */
+    id: string;
+    /** Human-readable description of what this rule does */
+    description: string;
+    /**
+     * Check if this rule applies given the BPM and context.
+     *
+     * @param bpm - Current BPM
+     * @param context - Tempo context with band, transients, and beat info
+     * @returns `true` if this rule should be applied
+     */
+    applies(bpm: number, context: TempoRuleContext): boolean;
+    /**
+     * Modify grid decisions based on this rule.
+     *
+     * Receives the raw transients and original grid decisions so it can
+     * make informed decisions (e.g., check transient positions before
+     * overriding).
+     *
+     * @param decisions - Current grid decisions (may already be modified by prior rules)
+     * @param context - Tempo context with BPM, band, transients, and beat info
+     * @returns Modified grid decisions
+     */
+    apply(decisions: GridDecision[], context: TempoRuleContext): GridDecision[];
+}
+/**
+ * Configuration for the high BPM grid restriction rule.
+ */
+export interface HighBpmGridRestrictionConfig {
+    /**
+     * BPM threshold above which 16th notes are restricted to 8th notes.
+     * At this BPM, a 16th note is ~94ms — at the edge of playability.
+     * Default: 160.
+     */
+    restrict16thBpm?: number;
+    /**
+     * BPM threshold above which triplets are also restricted to straight 8th.
+     * At this BPM, a triplet 8th is ~100ms — at the edge of playability.
+     * Default: 200.
+     */
+    restrictTripletBpm?: number;
+}
+/**
+ * Restricts grid types at high BPMs for fundamental playability.
+ *
+ * At high tempos, 16th notes and triplets become unplayable:
+ * - 160 BPM = 93.75ms per 16th note
+ * - 200 BPM = 100ms per triplet 8th
+ *
+ * This rule modifies grid decisions (not quantization) so the quantization
+ * pass snaps transients from their original timestamps to the coarser grid.
+ *
+ * Only applies to `mid` and `high` bands — `low` is already forced to
+ * `straight_8th` by `RhythmQuantizer.getBandGridType()`.
+ *
+ * When overriding a grid decision:
+ * - Sets `confidence: 1.0` (forced/authoritative)
+ * - Clears `straightAvgOffset` and `tripletAvgOffset` (they no longer reflect
+ *   the chosen grid)
+ *
+ * This matches the pattern used by `RhythmQuantizer.getBandGridType()` at
+ * line 714-719 for forced grid decisions.
+ */
+export declare class HighBpmGridRestrictionRule implements TempoQuantizationRule {
+    readonly id = "high-bpm-grid-restriction";
+    readonly description = "Restricts 16th notes and triplets to 8th notes at high BPMs for playability";
+    private readonly restrict16thBpm;
+    private readonly restrictTripletBpm;
+    constructor(config?: HighBpmGridRestrictionConfig);
+    applies(bpm: number, context: TempoRuleContext): boolean;
+    apply(decisions: GridDecision[], context: TempoRuleContext): GridDecision[];
+}
+/**
+ * Configuration for the TempoAwareQuantizer.
+ */
+export interface TempoAwareQuantizerConfig {
+    /**
+     * Ordered list of tempo quantization rules to apply.
+     * Rules are applied in array order — earlier rules' modifications
+     * are visible to later rules.
+     */
+    rules: TempoQuantizationRule[];
+    /**
+     * Whether tempo-aware quantization is enabled (default: true).
+     * When disabled, `applyRules()` returns the decisions unchanged.
+     */
+    enabled?: boolean;
+}
+/**
+ * Default configuration for tempo-aware quantization.
+ *
+ * Includes the `HighBpmGridRestrictionRule` with default thresholds:
+ * - 16th notes restricted at 160 BPM
+ * - Triplets restricted at 200 BPM
+ */
+export declare const DEFAULT_TEMPO_AWARE_CONFIG: TempoAwareQuantizerConfig;
+/**
+ * Applies BPM-based rules to constrain the quantization grid.
+ *
+ * Plugs into the decide-then-quantize flow as a middleware layer between
+ * grid decision and quantization:
+ *
+ * ```
+ * RhythmQuantizer.decideGrids()  →  base grid decisions
+ *         ↓
+ * TempoAwareQuantizer.decideGrids()  →  BPM-constrained decisions
+ *         ↓
+ * RhythmQuantizer.quantizeToGrids()  →  quantize from original timestamps
+ * ```
+ *
+ * Internally holds a `RhythmQuantizer` instance for the base grid decisions.
+ * Can also be used in standalone mode via `applyRules()` if you already have
+ * base grid decisions and just want to apply tempo rules.
+ *
+ * @example
+ * ```typescript
+ * // Full flow: base decisions → rules → final decisions
+ * const tempoQuantizer = new TempoAwareQuantizer({
+ *   rules: [new HighBpmGridRestrictionRule({ restrict16thBpm: 170 })],
+ * });
+ * const finalDecisions = tempoQuantizer.decideGrids(
+ *   transients, unifiedBeatMap, 'mid'
+ * );
+ *
+ * // Standalone: apply rules to existing decisions
+ * const modified = tempoQuantizer.applyRules(baseDecisions, context);
+ * ```
+ */
+export declare class TempoAwareQuantizer {
+    private readonly config;
+    private readonly rhythmQuantizer;
+    /**
+     * Create a new TempoAwareQuantizer.
+     *
+     * @param config - Configuration specifying rules and enabled state.
+     *   Defaults to `DEFAULT_TEMPO_AWARE_CONFIG` (high BPM restriction rule).
+     * @param rhythmQuantizer - Optional RhythmQuantizer instance for base grid
+     *   decisions. When omitted, a default RhythmQuantizer is created. Pass an
+     *   existing instance to share configuration (e.g., intensity filtering).
+     */
+    constructor(config?: TempoAwareQuantizerConfig, rhythmQuantizer?: RhythmQuantizer);
+    /**
+     * Get the current configuration.
+     *
+     * @returns A copy of the current configuration
+     */
+    getConfig(): TempoAwareQuantizerConfig;
+    /**
+     * Decide grid types with BPM-aware rule application.
+     *
+     * Orchestrates the full flow:
+     * 1. Gets base grid decisions from `RhythmQuantizer.decideGrids()`
+     * 2. Builds a `TempoRuleContext` from the beat map and transients
+     * 3. Applies each applicable rule in order
+     * 4. Returns the final, BPM-constrained grid decisions
+     *
+     * The returned grid decisions are suitable for passing directly to
+     * `RhythmQuantizer.quantizeToGrids()` for the actual quantization pass.
+     *
+     * @param transients - Raw transients for this band (original timestamps)
+     * @param unifiedBeatMap - Unified beat map providing BPM and beat grid
+     * @param band - Frequency band being processed ('low', 'mid', or 'high')
+     * @returns Grid decisions with BPM-based constraints applied
+     */
+    decideGrids(transients: TransientResult[], unifiedBeatMap: UnifiedBeatMap, band: 'low' | 'mid' | 'high'): GridDecision[];
+    /**
+     * Apply tempo-aware rules to existing grid decisions.
+     *
+     * Iterates through the configured rules in order. Each rule's `apply()`
+     * receives the decisions (possibly modified by earlier rules) and returns
+     * the modified decisions. This chaining allows rules to build on each other.
+     *
+     * When disabled (config `enabled: false`), returns decisions unchanged.
+     *
+     * @param decisions - Grid decisions from `RhythmQuantizer.decideGrids()`
+     * @param context - Tempo context with BPM, band, transients, and beat info
+     * @returns Modified grid decisions with tempo rules applied
+     */
+    applyRules(decisions: GridDecision[], context: TempoRuleContext): GridDecision[];
+}
+//# sourceMappingURL=TempoAwareQuantizer.d.ts.map

package/dist/core/analysis/beat/TempoAwareQuantizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TempoAwareQuantizer.d.ts","sourceRoot":"","sources":["../../../../src/core/analysis/beat/TempoAwareQuantizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAM7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IAEZ,uCAAuC;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAE5B,qCAAqC;IACrC,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAE7B,wEAAwE;IACxE,UAAU,EAAE,eAAe,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,qBAAqB;IAClC,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IAEX,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAEzD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAAC;CAC/E;AAUD;;GAEG;AACH,MAAM,WAAW,4BAA4B;IACzC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,0BAA2B,YAAW,qBAAqB;IACpE,QAAQ,CAAC,EAAE,+BAA+B;IAC1C,QAAQ,CAAC,WAAW,iFAAiF;IAErG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAEhC,MAAM,GAAE,4BAAiC;IAKrD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO;IAUxD,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE;CAqC9E;AAMD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;;OAIG;IACH,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAE/B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,yBAGxC,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAElD;;;;;;;;OAQG;gBAEC,MAAM,GAAE,yBAAsD,EAC9D,eAAe,CAAC,EAAE,eAAe;IAMrC;;;;OAIG;IACH,SAAS,IAAI,yBAAyB;IAItC;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CACP,UAAU,EAAE,eAAe,EAAE,EAC7B,cAAc,EAAE,cAAc,EAC9B,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAC7B,YAAY,EAAE;IAkBjB;;;;;;;;;;;;OAYG;IACH,UAAU,CACN,SAAS,EAAE,YAAY,EAAE,EACzB,OAAO,EAAE,gBAAgB,GAC1B,YAAY,EAAE;CAepB"}