playlist-data-engine 1.1.0

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

@@ -0,0 +1,366 @@
+/**
+ * Level Export Types
+ *
+ * Types for exporting and importing rhythm game levels in a format compatible
+ * with the playlist-data-showcase app's import/export functionality.
+ *
+ * This format supports both:
+ * - Procedurally generated levels (from LevelGenerator)
+ * - Manually charted levels (from showcase app chart editor)
+ *
+ * Part of the Pitch Detection & Button Mapping pipeline - Phase 4.2
+ */
+import type { SubdivisionType, BeatSource } from './BeatMap.js';
+import type { Band } from '../generation/RhythmGenerator.js';
+/**
+ * Chart style determining key layout
+ * - 'ddr': 4-key dance pad style (up, down, left, right)
+ * - 'guitar': 5-fret guitar hero style (1, 2, 3, 4, 5)
+ */
+export type ChartStyle = 'ddr' | 'guitar' | 'tap';
+/**
+ * A detected beat in the full beat map export format
+ */
+export interface FullExportDetectedBeat {
+    /** Timestamp in seconds */
+    timestamp: number;
+    /** Position within the measure */
+    beatInMeasure: number;
+    /** Whether this is a downbeat */
+    isDownbeat: boolean;
+    /** Measure number */
+    measureNumber: number;
+    /** Onset intensity (0-1) */
+    intensity: number;
+    /** Detection confidence (0-1) */
+    confidence: number;
+    /** Optional required key for rhythm game */
+    requiredKey?: string;
+}
+/**
+ * A merged beat (detected or interpolated) in the full beat map export format
+ */
+export interface FullExportMergedBeat {
+    /** Timestamp in seconds */
+    timestamp: number;
+    /** Position within the measure */
+    beatInMeasure: number;
+    /** Whether this is a downbeat */
+    isDownbeat: boolean;
+    /** Measure number */
+    measureNumber: number;
+    /** Onset intensity (0-1) */
+    intensity: number;
+    /** Detection confidence (0-1) */
+    confidence: number;
+    /** Optional required key for rhythm game */
+    requiredKey?: string;
+    /** Whether this beat was detected or interpolated */
+    source: BeatSource;
+    /** Distance to nearest detected beat (for interpolated beats) */
+    distanceToAnchor?: number;
+    /** Timestamp of nearest detected beat (for interpolated beats) */
+    nearestAnchorTimestamp?: number;
+}
+/**
+ * Metadata about the interpolation process
+ */
+export interface InterpolatedMetadataJSON {
+    /** Quarter note interval in seconds */
+    quarterNoteInterval: number;
+    /** Quarter note BPM (60 / quarterNoteInterval) */
+    quarterNoteBpm: number;
+    /** Confidence of quarter note detection */
+    quarterNoteConfidence: number;
+    /** Total detected beats count */
+    detectedBeatCount: number;
+    /** Total merged beats count (detected + interpolated) */
+    mergedBeatCount: number;
+}
+/**
+ * Subdivision configuration in JSON-serializable format
+ */
+export interface SubdivisionConfigJSON {
+    /** Subdivision assignments as array of [beatIndex, subdivisionType] tuples */
+    beatSubdivisions: [number, SubdivisionType][];
+    /** Default subdivision for beats not in the array */
+    defaultSubdivision: SubdivisionType;
+}
+/**
+ * Metadata about the subdivision process
+ */
+export interface SubdivisionMetadataJSON {
+    /** Original beat count before subdivision */
+    originalBeatCount: number;
+    /** Beat count after subdivision */
+    subdividedBeatCount: number;
+    /** Average density multiplier */
+    averageDensityMultiplier: number;
+    /** Number of explicitly subdivided beats */
+    explicitBeatCount: number;
+}
+/**
+ * A subdivided beat in the full beat map export format
+ * Includes procedural extensions for procedurally generated levels
+ */
+export interface FullExportSubdividedBeat {
+    /** Timestamp in seconds */
+    timestamp: number;
+    /** Position within the measure (decimal for subdivisions) */
+    beatInMeasure: number;
+    /** Whether this is a downbeat */
+    isDownbeat: boolean;
+    /** Measure number */
+    measureNumber: number;
+    /** Onset intensity (0-1) */
+    intensity: number;
+    /** Detection confidence (0-1) */
+    confidence: number;
+    /** Required key for this beat */
+    requiredKey?: string;
+    /** Whether this beat was originally detected */
+    isDetected: boolean;
+    /** Index of original beat in UnifiedBeatMap */
+    originalBeatIndex?: number;
+    /** The subdivision type that created this beat */
+    subdivisionType: SubdivisionType;
+    /** Index into the original quarter note (procedural only) */
+    quarterNoteIndex?: number;
+    /** Position within the quarter note (procedural only) */
+    subdivisionPosition?: number;
+    /** Which frequency band this beat originated from (procedural only) */
+    sourceBand?: Band;
+    /** Quantization error in milliseconds (procedural only) */
+    quantizationError?: number;
+}
+/**
+ * Complete subdivision data for export
+ */
+export interface SubdivisionExportData {
+    /** Subdivision configuration */
+    config: SubdivisionConfigJSON;
+    /** Subdivided beats with keys assigned */
+    beats: FullExportSubdividedBeat[];
+    /** Subdivision metadata */
+    metadata: SubdivisionMetadataJSON;
+}
+/**
+ * Chart metadata for export
+ */
+export interface ChartExportData {
+    /** Chart style (ddr or guitar) */
+    style: ChartStyle;
+    /** Number of keys/frets used */
+    keyCount: number;
+    /** Array of keys used in this chart */
+    usedKeys: string[];
+}
+/**
+ * Metadata specific to procedurally generated levels
+ * Only present when generationSource is 'procedural'
+ */
+export interface ProceduralGenerationMetadata {
+    /** Difficulty preset used */
+    difficulty: string;
+    /** Weight given to pitch analysis (0-1) */
+    pitchInfluenceWeight: number;
+    /** Button patterns used in generation */
+    patternsUsed: string[];
+    /** Controller mode used */
+    controllerMode: 'ddr' | 'guitar_hero' | 'tap';
+    /** Seed used for reproducibility */
+    seed?: string;
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Direction statistics from melody contour analysis */
+    directionStats?: {
+        up: number;
+        down: number;
+        stable: number;
+        none: number;
+    };
+    /** Interval statistics from melody contour analysis */
+    intervalStats?: {
+        unison: number;
+        small: number;
+        medium: number;
+        large: number;
+        very_large: number;
+    };
+    /** Rhythm metadata summary */
+    rhythmMetadata?: {
+        difficulty: string;
+        bandsAnalyzed: Band[];
+        transientsDetected: number;
+        averageDensity: number;
+    };
+}
+/**
+ * Complete beat map data for export/import
+ *
+ * This is the unified format that supports both:
+ * - Procedurally generated levels (from LevelGenerator)
+ * - Manually charted levels (from showcase app chart editor)
+ *
+ * The showcase app ignores extra fields, so procedural-specific fields
+ * can be safely added without breaking compatibility.
+ *
+ * @example
+ * ```typescript
+ * // Export a generated level
+ * const exportData = LevelSerializer.toExportData(generatedLevel);
+ * const json = JSON.stringify(exportData);
+ *
+ * // Import a level
+ * const data = JSON.parse(json) as FullBeatMapExportData;
+ * const level = LevelSerializer.fromExportData(data);
+ * ```
+ */
+export interface FullBeatMapExportData {
+    /** Format version (always 1) */
+    version: 1;
+    /** Format identifier (always 'full-beatmap') */
+    format: 'full-beatmap';
+    /** Unique identifier for the audio source */
+    audioId: string;
+    /** Optional audio title for display purposes */
+    audioTitle?: string;
+    /** Unix timestamp when this level was exported */
+    exportedAt: number;
+    /** Duration of the audio in seconds */
+    duration: number;
+    /** Quarter note BPM (60 / quarterNoteInterval) */
+    quarterNoteBpm: number;
+    /** Confidence of quarter note detection (0-1) */
+    quarterNoteConfidence: number;
+    /** Original detected beats from audio analysis */
+    detectedBeats: FullExportDetectedBeat[];
+    /** Merged beats (detected + interpolated) */
+    mergedBeats: FullExportMergedBeat[];
+    /** Metadata about the interpolation process */
+    interpolatedMetadata: InterpolatedMetadataJSON;
+    /** Subdivision data (null if no subdivision applied) */
+    subdivision: SubdivisionExportData | null;
+    /** Chart style and key information (null if no chart) */
+    chart: ChartExportData | null;
+    /**
+     * Identifies the song this level was created for.
+     * Absent in v1 exports for backward compatibility.
+     */
+    trackReference?: TrackReference;
+    /** Source of this level (manual or procedural) */
+    generationSource?: 'manual' | 'procedural';
+    /** Additional metadata for procedurally generated levels */
+    generationMetadata?: ProceduralGenerationMetadata;
+}
+/**
+ * Result of attempting to import a beat map
+ */
+export interface FullBeatMapImportResult {
+    /** Whether the import was successful */
+    success: boolean;
+    /** The imported data if successful */
+    data?: FullBeatMapExportData;
+    /** Error message if import failed */
+    error?: string;
+    /** Validation warnings (non-fatal issues) */
+    warnings?: string[];
+}
+/**
+ * Identifies the song that a level was created for.
+ * Embedded in exported level files so the UI can validate the correct song
+ * is selected on import and tell the user which playlist/track to switch to.
+ */
+export interface TrackReference {
+    /** Arweave transaction ID of the playlist that contains this track */
+    playlistTxId?: string;
+    /** Display name of the playlist */
+    playlistName?: string;
+    /** Track ID (e.g. "ethereum-0xContract-1" or "AR-{tx_id}") */
+    trackId: string;
+    /** Unique instance ID for the game engine */
+    trackUuid: string;
+    /** 0-based index of the track within the playlist */
+    trackIndex: number;
+    /** Arweave transaction ID for the track's audio (only for AR tracks) */
+    txId?: string;
+    /** Track title */
+    title: string;
+    /** Track artist */
+    artist: string;
+    /** URL to the audio file */
+    audioUrl: string;
+    /** URL to the track's cover image (optional) */
+    imageUrl?: string;
+    /** Duration of the audio in seconds */
+    duration: number;
+}
+/**
+ * Result of validating whether the currently selected track matches the
+ * track referenced in an imported level file.
+ */
+export interface TrackMatchResult {
+    /** True when the current track is the one the level was built for */
+    matches: boolean;
+    /** Human-readable details about any mismatch (empty when matches is true) */
+    mismatchDetails: string[];
+    /** When mismatched, describes the track the user needs to switch to */
+    requiredTrack?: {
+        title: string;
+        artist: string;
+        playlistName?: string;
+        trackIndex: number;
+    };
+}
+/**
+ * Validate whether the currently selected track matches the track reference
+ * embedded in a level file.
+ *
+ * Matching strategy:
+ * 1. Compare by `trackId` (exact)
+ * 2. Fall back to `title + artist` (case-insensitive)
+ *
+ * @param levelTrackRef - The track reference from the imported level file
+ * @param currentTrack - The track currently selected in the showcase app
+ * @returns Match result with details about any mismatch
+ */
+export declare function validateTrackMatch(levelTrackRef: TrackReference, currentTrack: {
+    id: string;
+    title: string;
+    artist: string;
+    playlist_index: number;
+    tx_id?: string;
+}): TrackMatchResult;
+/**
+ * Check if an unknown value is a valid FullBeatMapExportData
+ */
+export declare function isFullBeatMapExportData(value: unknown): value is FullBeatMapExportData;
+/**
+ * A collection of difficulty levels for the same song, exported as a single file.
+ *
+ * Each difficulty is a full FullBeatMapExportData so it can be independently
+ * deserialized. The pack-level trackReference applies to all difficulties.
+ */
+export interface LevelPackExport {
+    /** Format version (always 1) */
+    version: 1;
+    /** Format identifier (always 'level-pack') */
+    format: 'level-pack';
+    /** Unix timestamp when this pack was exported */
+    exportedAt: number;
+    /** Track reference identifying the song (shared across all difficulties) */
+    trackReference?: TrackReference;
+    /** Per-difficulty level data. Keys that exist have generated levels. */
+    difficulties: {
+        natural?: FullBeatMapExportData;
+        easy?: FullBeatMapExportData;
+        medium?: FullBeatMapExportData;
+        hard?: FullBeatMapExportData;
+        custom?: FullBeatMapExportData;
+    };
+}
+/**
+ * Check if an unknown value is a valid LevelPackExport.
+ */
+export declare function isLevelPackExport(value: unknown): value is LevelPackExport;
+//# sourceMappingURL=LevelExport.d.ts.map

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

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

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

@@ -0,0 +1,70 @@
+/**
+ * Playlist-related type definitions
+ * Based on specs/001-core-engine/SPEC.md
+ */
+/**
+ * ServerlessPlaylist - The playlist container
+ * This is the structure of the JSON file fetched directly from Arweave
+ */
+export interface ServerlessPlaylist {
+    name: string;
+    description?: string;
+    image: string;
+    creator: string;
+    genre?: string;
+    tags?: string[];
+    tracks: PlaylistTrack[];
+}
+/**
+ * PlaylistTrack - Single source of truth for a track
+ * Result of merging "Outer Shell" (Blockchain Data) with "Inner Core" (Parsed Metadata)
+ */
+export interface PlaylistTrack {
+    id: string;
+    uuid: string;
+    playlist_index: number;
+    chain_name: string;
+    token_address?: string;
+    token_id?: string;
+    tx_id?: string;
+    platform: string;
+    title: string;
+    artist: string;
+    description?: string;
+    album?: string;
+    image_url: string;
+    /** Optional thumbnail URL extracted from image_thumb or image_thumb_url fields */
+    image_thumb_url?: string;
+    audio_url: string;
+    /** Optional uncompressed audio URL for high-fidelity playback */
+    audio_url_lossless?: string;
+    duration: number;
+    genre: string;
+    tags: string[];
+    bpm?: number;
+    key?: string;
+    attributes?: Record<string, string | number>;
+}
+/**
+ * RawArweavePlaylist - The raw input schema
+ * This is what the engine receives from Arweave before parsing
+ */
+export interface RawArweavePlaylist {
+    name: string;
+    image: string;
+    creator: string;
+    description?: string;
+    genre?: string;
+    tags?: string[];
+    tracks: Array<{
+        chain_name: string;
+        token_address?: string;
+        token_id?: string;
+        tx_id?: string;
+        platform: string;
+        id?: string;
+        uuid?: string;
+        metadata: string;
+    }>;
+}
+//# sourceMappingURL=Playlist.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Playlist.d.ts","sourceRoot":"","sources":["../../../src/core/types/Playlist.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAE/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAGhB,MAAM,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAE1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IAEvB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IAGjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IAGjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IAGb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAChD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAEV,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QAGd,QAAQ,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACN"}

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

@@ -0,0 +1,94 @@
+/**
+ * Prestige System Types
+ *
+ * The Prestige System allows players to reset their character after mastering a track
+ * in exchange for a visual badge upgrade. Uses 1.5x scaling per prestige level for
+ * both plays AND XP requirements.
+ *
+ * Mastery Requirements (Dual System):
+ * - Must meet BOTH plays AND XP thresholds to unlock mastery
+ * - Base: 10 plays + 1,000 XP
+ * - 1.5x scaling per prestige level
+ * - Dual requirement prevents "cheesing" (play/pause spam) since XP requires actual engagement
+ */
+/**
+ * Prestige level type (0-10, where 0 = no prestige, 1-10 = Roman numerals I-X)
+ */
+export type PrestigeLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+/**
+ * Roman numeral representations for prestige levels
+ */
+export declare const PRESTIGE_ROMAN_NUMERALS: Record<PrestigeLevel, string>;
+/**
+ * Maximum prestige level achievable
+ */
+export declare const MAX_PRESTIGE_LEVEL: 10;
+/**
+ * Base number of plays required to master a track at prestige level 0
+ */
+export declare const BASE_PLAYS_THRESHOLD: 10;
+/**
+ * Base XP required to master a track at prestige level 0
+ */
+export declare const BASE_XP_THRESHOLD: 1000;
+/**
+ * Scaling factor per prestige level (1.5x)
+ */
+export declare const PRESTIGE_SCALING_FACTOR: 1.5;
+/**
+ * Custom thresholds for a prestige level (allows overriding defaults)
+ * null means use calculated value, undefined means no override set
+ */
+export interface CustomThresholds {
+    /** Custom plays threshold, or null to use calculated value */
+    playsThreshold?: number | null;
+    /** Custom XP threshold, or null to use calculated value */
+    xpThreshold?: number | null;
+}
+/**
+ * Complete prestige information for a character/track combination
+ */
+export interface PrestigeInfo {
+    /** Current prestige level (0-10) */
+    prestigeLevel: PrestigeLevel;
+    /** Current number of plays for this track */
+    currentPlays: number;
+    /** Current XP earned for this track */
+    currentXP: number;
+    /** Required plays to master at current prestige level */
+    playsThreshold: number;
+    /** Required XP to master at current prestige level */
+    xpThreshold: number;
+    /** Progress toward plays requirement (0-1) */
+    playsProgress: number;
+    /** Progress toward XP requirement (0-1) */
+    xpProgress: number;
+    /** Whether track is mastered (meets BOTH plays AND XP thresholds) */
+    isMastered: boolean;
+    /** Whether character can prestige (mastered AND not at max prestige) */
+    canPrestige: boolean;
+    /** Whether character is at max prestige level */
+    isMaxPrestige: boolean;
+}
+/**
+ * Result of a prestige operation
+ */
+export interface PrestigeResult {
+    /** Whether the prestige operation succeeded */
+    success: boolean;
+    /** New prestige level after operation */
+    newPrestigeLevel: PrestigeLevel;
+    /** Previous prestige level before operation */
+    previousPrestigeLevel: PrestigeLevel;
+    /** Human-readable result message */
+    message: string;
+}
+/**
+ * Type guard to check if a value is a valid PrestigeLevel
+ */
+export declare function isPrestigeLevel(value: unknown): value is PrestigeLevel;
+/**
+ * Convert a number to a PrestigeLevel (clamped to valid range)
+ */
+export declare function toPrestigeLevel(value: number): PrestigeLevel;
+//# sourceMappingURL=Prestige.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Prestige.d.ts","sourceRoot":"","sources":["../../../src/core/types/Prestige.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;AAEvE;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAYxD,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAG,EAAW,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAG,EAAW,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAG,IAAa,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAG,GAAY,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,oCAAoC;IACpC,aAAa,EAAE,aAAa,CAAC;IAC7B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAC;IACpB,wEAAwE;IACxE,WAAW,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,aAAa,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,gBAAgB,EAAE,aAAa,CAAC;IAChC,+CAA+C;IAC/C,qBAAqB,EAAE,aAAa,CAAC;IACrC,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAKtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAG5D"}