cinematic-renderer2d 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1663 @@
+/**
+ * Quality and Performance Types for cinematicRenderer2D
+ *
+ * These types define the adaptive quality system that monitors performance
+ * and automatically adjusts rendering quality to maintain target frame rates.
+ *
+ * Requirements: 8.1, 8.2, 8.3, 8.4, 8.5 - Adaptive quality system
+ */
+type QualityLevel$1 = 'low' | 'medium' | 'high' | 'ultra' | 'auto';
+interface QualitySettings {
+    /** Maximum number of particles to render */
+    particleCount: number;
+    /** Canvas resolution multiplier (0.5 = half resolution) */
+    canvasResolution: number;
+    /** Animation interpolation precision (higher = smoother) */
+    animationPrecision: number;
+    /** Whether to enable blur effects */
+    enableBlur: boolean;
+    /** Whether to enable shadow effects */
+    enableShadows: boolean;
+    /** Target frame rate for this quality level */
+    targetFps: number;
+    /** Whether to enable advanced visual effects */
+    enableAdvancedEffects: boolean;
+    /** Texture quality multiplier */
+    textureQuality: number;
+    /** Whether to use hardware acceleration */
+    useHardwareAcceleration: boolean;
+}
+interface PerformanceMetrics {
+    /** Current frames per second */
+    fps: number;
+    /** Frame time in milliseconds */
+    frameTime: number;
+    /** Memory usage in MB */
+    memoryUsage?: number;
+    /** GPU memory usage in MB */
+    gpuMemory?: number;
+    /** Number of active particles */
+    activeParticles: number;
+    /** Number of active layers */
+    activeLayers: number;
+    /** Number of DOM nodes created */
+    domNodes: number;
+    /** Canvas draw calls per frame */
+    drawCalls: number;
+    /** Asset loading time in milliseconds */
+    assetLoadTime?: number;
+    /** Compilation time in milliseconds */
+    compilationTime?: number;
+}
+interface DeviceCapabilities {
+    /** Device memory in GB */
+    memory?: number;
+    /** Number of CPU cores */
+    cores?: number;
+    /** GPU information */
+    gpu?: string;
+    /** User prefers reduced motion */
+    prefersReducedMotion: boolean;
+    /** Device power mode */
+    powerMode?: 'high-performance' | 'balanced' | 'power-saver';
+    /** Screen refresh rate */
+    refreshRate?: number;
+    /** Device pixel ratio */
+    devicePixelRatio: number;
+    /** Whether device supports hardware acceleration */
+    supportsHardwareAcceleration: boolean;
+    /** Maximum texture size supported */
+    maxTextureSize?: number;
+    /** Whether device is mobile */
+    isMobile: boolean;
+    /** Network connection type */
+    connectionType?: 'slow-2g' | '2g' | '3g' | '4g' | '5g' | 'wifi' | 'ethernet';
+}
+/** Quality system configuration */
+interface QualitySystemConfig {
+    /** How often to check performance (milliseconds) */
+    monitoringInterval: number;
+    /** FPS threshold for quality reduction */
+    fpsThreshold: number;
+    /** Number of consecutive bad frames before reducing quality */
+    badFrameThreshold: number;
+    /** Number of consecutive good frames before increasing quality */
+    goodFrameThreshold: number;
+    /** Whether to respect user preferences */
+    respectUserPreferences: boolean;
+    /** Whether to use device capability detection */
+    useDeviceDetection: boolean;
+    /** Custom quality level mappings */
+    customLevels?: Record<string, QualitySettings>;
+}
+/** Performance monitoring event data */
+interface PerformanceEvent {
+    /** Event type */
+    type: 'fps-drop' | 'memory-warning' | 'quality-change' | 'performance-good';
+    /** Current performance metrics */
+    metrics: PerformanceMetrics;
+    /** Previous quality level (for quality-change events) */
+    previousQuality?: QualityLevel$1;
+    /** New quality level (for quality-change events) */
+    newQuality?: QualityLevel$1;
+    /** Timestamp of the event */
+    timestamp: number;
+    /** Additional context data */
+    context?: Record<string, any>;
+}
+/** Quality preset configurations */
+declare const QUALITY_PRESETS: Record<QualityLevel$1, QualitySettings>;
+
+/**
+ * Main interface for the CinematicRenderer2D engine
+ */
+
+interface ICinematicRenderer2D {
+    mount(): Promise<void>;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    destroy(): void;
+    seek(timeMs: number): void;
+    goToEvent(eventId: string): void;
+    goToScene(sceneId: string): void;
+    setQuality(level: QualityLevel$1): void;
+    resize(width: number, height: number): void;
+    on(event: string, callback: Function): void;
+    off(event: string, callback: Function): void;
+    getCurrentTime(): number;
+    getDuration(): number;
+    isPlaying(): boolean;
+    isPaused(): boolean;
+    getCurrentEvent(): string | null;
+    getCurrentScene(): string | null;
+    getState(): PlaybackState;
+    getQuality(): QualityLevel$1;
+    isMounted(): boolean;
+}
+
+/**
+ * JSON Specification Types for cinematicRenderer2D
+ *
+ * These types define the structure of JSON specifications that describe
+ * cinematic experiences with events, scenes, layers, and animations.
+ *
+ * Requirements: 3.1, 3.5 - JSON specification processing with schema versioning
+ */
+interface CinematicSpec {
+    /** Schema version for backward compatibility (e.g., "1.0.0") */
+    schemaVersion: string;
+    /** Engine configuration and global settings */
+    engine: EngineConfig;
+    /** Array of cinematic events that define high-level sequences */
+    events: CinematicEvent[];
+    /** Array of scenes containing layers and timing information */
+    scenes: CinematicScene[];
+    /** Optional asset definitions for preloading and caching */
+    assets?: AssetDefinition$1[];
+}
+interface EngineConfig {
+    /** Target frame rate (default: 60, supports up to 120fps) */
+    targetFps?: number;
+    /** Quality level for performance optimization */
+    quality?: QualityLevel;
+    /** Enable debug mode with performance overlay */
+    debug?: boolean;
+    /** Auto-start playback after mounting */
+    autoplay?: boolean;
+}
+interface CinematicEvent {
+    /** Unique identifier for the event */
+    id: string;
+    /** Human-readable name for the event */
+    name: string;
+    /** Array of scene IDs that make up this event */
+    scenes: string[];
+    /** Optional transitions between scenes */
+    transitions?: TransitionSpec[];
+}
+interface CinematicScene {
+    /** Unique identifier for the scene */
+    id: string;
+    /** Human-readable name for the scene */
+    name: string;
+    /** Duration of the scene in milliseconds */
+    duration: number;
+    /** Array of layers that make up this scene */
+    layers: LayerSpec[];
+    /** Optional audio tracks for this scene */
+    audio?: AudioTrackSpec[];
+}
+interface LayerSpec {
+    /** Unique identifier for the layer */
+    id: string;
+    /** Layer type - determines which renderer handles this layer */
+    type: LayerType;
+    /** Z-index for layer ordering (higher values render on top) */
+    zIndex: number;
+    /** Layer-specific configuration properties */
+    config: LayerConfig;
+    /** Optional animation tracks for this layer */
+    animations?: AnimationTrackSpec[];
+}
+/** Supported layer types for different rendering backends */
+type LayerType = 'gradient' | 'image' | 'textBlock' | 'vignette' | 'glowOrb' | 'noiseOverlay' | 'particles' | 'starfield' | 'dust' | 'nebulaNoise' | 'webgl-custom';
+/** Base configuration for all layer types */
+interface LayerConfig {
+    /** Layer opacity (0-1) */
+    opacity?: number;
+    /** Layer visibility */
+    visible?: boolean;
+    /** Position and transform properties */
+    transform?: TransformConfig;
+    /** Layer-specific properties (varies by type) */
+    [key: string]: any;
+}
+/** Transform configuration for layer positioning and animation */
+interface TransformConfig {
+    /** X position (pixels or percentage) */
+    x?: number | string;
+    /** Y position (pixels or percentage) */
+    y?: number | string;
+    /** Scale factor */
+    scale?: number;
+    /** Rotation in degrees */
+    rotation?: number;
+    /** Transform origin point */
+    origin?: string;
+}
+interface AnimationTrackSpec {
+    /** CSS property path to animate (e.g., 'opacity', 'transform.scale', 'filter.blur') */
+    property: string;
+    /** Starting value for the animation */
+    from: AnimationValue;
+    /** Ending value for the animation */
+    to: AnimationValue;
+    /** Animation start time in milliseconds */
+    startMs: number;
+    /** Animation end time in milliseconds */
+    endMs: number;
+    /** Easing function name or cubic-bezier values */
+    easing?: EasingType;
+    /** Whether to loop the animation */
+    loop?: boolean;
+    /** Whether to reverse the animation on each loop */
+    yoyo?: boolean;
+}
+/** Supported animation value types */
+type AnimationValue = number | string | boolean | AnimationValueObject;
+/** Complex animation values for multi-property animations */
+interface AnimationValueObject {
+    [key: string]: number | string | boolean;
+}
+/** Supported easing function types */
+type EasingType = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'ease-in-sine' | 'ease-out-sine' | 'ease-in-out-sine' | 'ease-in-quad' | 'ease-out-quad' | 'ease-in-out-quad' | 'ease-in-cubic' | 'ease-out-cubic' | 'ease-in-out-cubic' | 'ease-in-quart' | 'ease-out-quart' | 'ease-in-out-quart' | 'ease-in-quint' | 'ease-out-quint' | 'ease-in-out-quint' | 'ease-in-expo' | 'ease-out-expo' | 'ease-in-out-expo' | 'ease-in-circ' | 'ease-out-circ' | 'ease-in-out-circ' | 'ease-in-back' | 'ease-out-back' | 'ease-in-out-back' | 'ease-in-elastic' | 'ease-out-elastic' | 'ease-in-out-elastic' | 'ease-in-bounce' | 'ease-out-bounce' | 'ease-in-out-bounce' | `cubic-bezier(${number},${number},${number},${number})`;
+interface AudioTrackSpec {
+    /** Unique identifier for the audio track */
+    id: string;
+    /** Type of audio content */
+    type: AudioTrackType;
+    /** Source URL or asset ID for the audio file */
+    src: string;
+    /** Start time in milliseconds */
+    startMs: number;
+    /** End time in milliseconds (optional, defaults to audio duration) */
+    endMs?: number;
+    /** Volume level (0-1, default: 1) */
+    volume?: number;
+    /** Fade in duration in milliseconds */
+    fadeIn?: number;
+    /** Fade out duration in milliseconds */
+    fadeOut?: number;
+    /** Whether to loop the audio */
+    loop?: boolean;
+}
+/** Supported audio track types */
+type AudioTrackType = 'voiceover' | 'ambience' | 'transition' | 'music' | 'sfx';
+interface TransitionSpec {
+    /** Type of transition effect */
+    type: TransitionType;
+    /** Duration of the transition in milliseconds */
+    duration: number;
+    /** Easing function for the transition */
+    easing?: EasingType;
+    /** Additional transition-specific properties */
+    config?: TransitionConfig;
+}
+/** Supported transition types */
+type TransitionType = 'fade' | 'slide' | 'zoom' | 'wipe' | 'dissolve' | 'blur';
+/** Configuration for transition effects */
+interface TransitionConfig {
+    /** Direction for slide/wipe transitions */
+    direction?: 'up' | 'down' | 'left' | 'right' | 'in' | 'out';
+    /** Blur amount for blur transitions */
+    blurAmount?: number;
+    /** Custom properties for advanced transitions */
+    [key: string]: any;
+}
+interface AssetDefinition$1 {
+    /** Unique identifier for the asset */
+    id: string;
+    /** Type of asset */
+    type: AssetType$1;
+    /** Source URL for the asset */
+    src: string;
+    /** Whether to preload this asset */
+    preload?: boolean;
+    /** Fallback asset ID or URL if loading fails */
+    fallback?: string;
+    /** Additional metadata for the asset */
+    metadata?: AssetMetadata$1;
+}
+/** Supported asset types */
+type AssetType$1 = 'image' | 'video' | 'audio' | 'font' | 'json' | 'binary';
+/** Asset metadata for optimization and caching */
+interface AssetMetadata$1 {
+    /** Expected file size in bytes */
+    size?: number;
+    /** MIME type */
+    mimeType?: string;
+    /** Cache duration in milliseconds */
+    cacheDuration?: number;
+    /** Asset dimensions for images/videos */
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    /** Audio duration in milliseconds */
+    duration?: number;
+}
+type QualityLevel = 'low' | 'medium' | 'high' | 'ultra' | 'auto';
+
+interface CinematicRenderer2DOptions {
+    container: HTMLElement;
+    spec: CinematicSpec;
+    autoplay?: boolean;
+    quality?: QualityLevel$1;
+    debug?: boolean;
+}
+type PlaybackState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'stopped' | 'destroyed';
+declare class CinematicRenderer2D implements ICinematicRenderer2D {
+    private _container;
+    private _spec;
+    private _compiledSpec;
+    private _options;
+    private eventListeners;
+    private _state;
+    private _currentTime;
+    private _duration;
+    private _currentEventId;
+    private _currentSceneId;
+    private _quality;
+    private _resizeListener;
+    private _scheduler;
+    private _qualitySystem;
+    private _audioSystem;
+    private _debugOverlay;
+    private _layerRegistry;
+    private _domRenderer;
+    private _canvas2DRenderer;
+    private _layers;
+    private _currentSceneLayers;
+    private _resizeObserver;
+    private _mounted;
+    constructor(options: CinematicRenderer2DOptions);
+    mount(): Promise<void>;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    destroy(): void;
+    seek(timeMs: number): void;
+    goToEvent(eventId: string): void;
+    goToScene(sceneId: string): void;
+    setQuality(level: QualityLevel$1): void;
+    resize(width: number, height: number): void;
+    on(event: string, callback: Function): void;
+    off(event: string, callback: Function): void;
+    getCurrentTime(): number;
+    getDuration(): number;
+    isPlaying(): boolean;
+    isPaused(): boolean;
+    getCurrentEvent(): string | null;
+    getCurrentScene(): string | null;
+    getState(): PlaybackState;
+    getQuality(): QualityLevel$1;
+    isMounted(): boolean;
+    getCurrentFps(): number;
+    getPerformanceMetrics(): PerformanceMetrics;
+    getQualitySettings(): QualitySettings;
+    getDeviceCapabilities(): DeviceCapabilities;
+    setMasterVolume(volume: number): void;
+    getMasterVolume(): number;
+    isWebAudioAvailable(): boolean;
+    getActiveAudioTrackCount(): number;
+    isDebugEnabled(): boolean;
+    toggleDebug(): void;
+    showDebug(): void;
+    hideDebug(): void;
+    protected emit(event: string, ...args: any[]): void;
+    private _onFrame;
+    private _setState;
+    private _calculateDuration;
+    private _calculateEventStartTime;
+    private _calculateSceneStartTime;
+    private _updateCurrentEventAndScene;
+    private _setupContainer;
+    private _setupResizeObserver;
+    private _setupResizeListener;
+    private _initializeRenderers;
+    private _initializeLayers;
+    private _updateCurrentSceneLayers;
+    private _mountLayer;
+    private _renderCurrentFrame;
+    private _getCurrentScene;
+    private _getLayerConfig;
+    private _resetLayersToInitialState;
+    private _destroyAllLayers;
+}
+
+/**
+ * Abstract base class for rendering backends
+ */
+
+declare abstract class RenderBackend {
+    protected container: HTMLElement;
+    constructor(container: HTMLElement);
+    abstract initialize(): void;
+    abstract render(layers: ICinematicLayer[], context: FrameContext$1): void;
+    abstract resize(width: number, height: number): void;
+    abstract destroy(): void;
+}
+
+/**
+ * Asset Management Types for cinematicRenderer2D
+ *
+ * These types define the asset loading, caching, and management system
+ * that handles images, videos, audio files, and other resources.
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4 - Comprehensive asset management
+ */
+interface Asset {
+    /** Unique identifier for the asset */
+    id: string;
+    /** Type of asset */
+    type: AssetType;
+    /** Source URL */
+    src: string;
+    /** Loaded asset data (varies by type) */
+    data: AssetData | null;
+    /** Whether the asset has finished loading */
+    loaded: boolean;
+    /** Loading error if any occurred */
+    error: Error | null;
+    /** Fallback asset ID or URL */
+    fallback?: string;
+    /** Asset metadata */
+    metadata: AssetMetadata;
+    /** Loading progress (0-1) */
+    progress: number;
+    /** Cache timestamp for expiration */
+    cachedAt?: number;
+    /** Asset size in bytes */
+    size?: number;
+}
+/** Union type for all possible asset data types */
+type AssetData = HTMLImageElement | HTMLVideoElement | HTMLAudioElement | AudioBuffer | FontFace | ArrayBuffer | string | object;
+/** Supported asset types */
+type AssetType = 'image' | 'video' | 'audio' | 'font' | 'json' | 'binary' | 'text';
+interface AssetDefinition {
+    /** Unique identifier for the asset */
+    id: string;
+    /** Type of asset */
+    type: AssetType;
+    /** Source URL for the asset */
+    src: string;
+    /** Whether to preload this asset */
+    preload?: boolean;
+    /** Fallback asset ID or URL if loading fails */
+    fallback?: string;
+    /** Additional metadata for the asset */
+    metadata?: Partial<AssetMetadata>;
+}
+/** Asset metadata for optimization and caching */
+interface AssetMetadata {
+    /** Expected file size in bytes */
+    size: number;
+    /** MIME type */
+    mimeType: string;
+    /** Cache duration in milliseconds */
+    cacheDuration: number;
+    /** Asset dimensions for images/videos */
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    /** Audio/video duration in milliseconds */
+    duration?: number;
+    /** Compression quality (0-1) */
+    quality?: number;
+    /** Whether asset supports streaming */
+    streamable?: boolean;
+    /** Asset priority for loading order */
+    priority?: AssetPriority;
+}
+/** Asset loading priority levels */
+type AssetPriority = 'critical' | 'high' | 'normal' | 'low' | 'lazy';
+interface AssetLoadProgress {
+    /** Number of assets loaded */
+    loaded: number;
+    /** Total number of assets to load */
+    total: number;
+    /** Currently loading asset ID */
+    currentAsset?: string;
+    /** Overall progress percentage (0-100) */
+    percentage: number;
+    /** Loading speed in bytes per second */
+    speed?: number;
+    /** Estimated time remaining in milliseconds */
+    estimatedTimeRemaining?: number;
+}
+/** Asset loading options */
+interface AssetLoadOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Number of retry attempts */
+    retries?: number;
+    /** Whether to use cache */
+    useCache?: boolean;
+    /** Custom headers for the request */
+    headers?: Record<string, string>;
+    /** CORS mode */
+    mode?: 'cors' | 'no-cors' | 'same-origin';
+    /** Credentials mode */
+    credentials?: 'omit' | 'same-origin' | 'include';
+}
+/** Asset cache configuration */
+interface AssetCacheConfig {
+    /** Maximum cache size in bytes */
+    maxSize: number;
+    /** Default cache duration in milliseconds */
+    defaultDuration: number;
+    /** Cache storage type */
+    storageType: 'memory' | 'indexeddb' | 'localstorage';
+    /** Whether to compress cached assets */
+    compress: boolean;
+    /** Cache eviction strategy */
+    evictionStrategy: 'lru' | 'lfu' | 'fifo';
+}
+
+/**
+ * Comprehensive asset management system for preloading and caching resources
+ *
+ * This system handles loading, caching, and management of various asset types
+ * including images, videos, audio files, fonts, and other resources with
+ * fallback handling, progress tracking, and performance optimization.
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4
+ */
+
+interface AssetManagerConfig {
+    /** Maximum number of concurrent downloads */
+    maxConcurrentLoads?: number;
+    /** Default timeout for asset loading in milliseconds */
+    defaultTimeout?: number;
+    /** Default number of retry attempts */
+    defaultRetries?: number;
+    /** Cache configuration */
+    cache?: Partial<AssetCacheConfig>;
+    /** Base URL for relative asset paths */
+    baseUrl?: string;
+}
+interface AssetManagerEvents {
+    'progress': (progress: AssetLoadProgress) => void;
+    'asset-loaded': (asset: Asset) => void;
+    'asset-error': (assetId: string, error: Error) => void;
+    'complete': (assets: Asset[]) => void;
+    'cache-full': (cacheSize: number) => void;
+}
+declare class AssetManager {
+    private _assets;
+    private _eventListeners;
+    private _loadingQueue;
+    private _activeLoads;
+    private _config;
+    private _cacheSize;
+    private _loadStartTime;
+    private _loadedBytes;
+    constructor(config?: AssetManagerConfig);
+    /**
+     * Load multiple assets with progress tracking and fallback handling
+     */
+    loadAssets(definitions: AssetDefinition[]): Promise<Asset[]>;
+    /**
+     * Get a loaded asset by ID
+     */
+    getAsset(id: string): Asset | null;
+    /**
+     * Check if an asset is loaded
+     */
+    isAssetLoaded(id: string): boolean;
+    /**
+     * Get all loaded assets
+     */
+    getAllAssets(): Asset[];
+    /**
+     * Get assets by type
+     */
+    getAssetsByType(type: AssetType): Asset[];
+    /**
+     * Preload a single asset
+     */
+    preloadAsset(definition: AssetDefinition): Promise<Asset>;
+    /**
+     * Clear all cached assets
+     */
+    clearCache(): void;
+    /**
+     * Remove specific asset from cache
+     */
+    removeAsset(id: string): boolean;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        totalAssets: number;
+        cacheSize: number;
+        maxCacheSize: number;
+        cacheUtilization: number;
+    };
+    /**
+     * Add event listener
+     */
+    on<K extends keyof AssetManagerEvents>(event: K, callback: AssetManagerEvents[K]): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof AssetManagerEvents>(event: K, callback: AssetManagerEvents[K]): void;
+    private _createAsset;
+    private _createDefaultMetadata;
+    private _resolveUrl;
+    private _getMimeType;
+    private _sortByPriority;
+    private _loadSingleAsset;
+    private _loadAssetData;
+    private _loadImage;
+    private _loadVideo;
+    private _loadAudio;
+    private _loadFont;
+    private _loadJson;
+    private _loadText;
+    private _loadBinary;
+    private _fetchWithTimeout;
+    private _estimateAssetSize;
+    private _enforceCache;
+    private _emitProgress;
+    private _emit;
+    private _isPromiseSettled;
+}
+
+/**
+ * Context objects passed to layers during mount and update operations
+ */
+
+interface LayerMountContext {
+    container: HTMLElement;
+    canvas?: HTMLCanvasElement;
+    renderer: RenderBackend;
+    assetManager: AssetManager;
+    layerConfig: Record<string, any>;
+}
+interface FrameContext$1 {
+    timeMs: number;
+    deltaMs: number;
+    quality: QualityLevel$1;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    devicePixelRatio: number;
+}
+
+/**
+ * Interface for cinematic layers - the building blocks of scenes
+ */
+
+interface ICinematicLayer {
+    readonly id: string;
+    readonly type: string;
+    readonly zIndex: number;
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+    resize?(width: number, height: number): void;
+    setVisible?(visible: boolean): void;
+    setOpacity?(opacity: number): void;
+}
+
+/**
+ * Compiled Runtime Types for cinematicRenderer2D
+ *
+ * These types represent the optimized, runtime-ready versions of the JSON specifications
+ * after parsing, validation, and compilation. All animation tracks are precompiled into
+ * optimized interpolation functions for maximum performance.
+ *
+ * Requirements: 3.1, 3.5 - Compiled runtime models with performance optimization
+ */
+
+interface CompiledSpec {
+    /** Map of event IDs to compiled event objects */
+    events: Map<string, CompiledEvent>;
+    /** Map of scene IDs to compiled scene objects */
+    scenes: Map<string, CompiledScene>;
+    /** Map of asset IDs to loaded asset objects */
+    assets: Map<string, Asset>;
+    /** Global engine configuration */
+    globalConfig: EngineConfig;
+    /** Schema version for compatibility checking */
+    schemaVersion: string;
+    /** Total duration of all content in milliseconds */
+    totalDuration: number;
+    /** Compilation timestamp for cache validation */
+    compiledAt: number;
+}
+interface CompiledEvent {
+    /** Unique identifier for the event */
+    id: string;
+    /** Human-readable name for the event */
+    name: string;
+    /** Array of compiled scene objects (not just IDs) */
+    scenes: CompiledScene[];
+    /** Compiled transition effects between scenes */
+    transitions: CompiledTransition[];
+    /** Total duration of this event in milliseconds */
+    duration: number;
+    /** Start time of this event in the global timeline */
+    startTime: number;
+}
+interface CompiledScene {
+    /** Unique identifier for the scene */
+    id: string;
+    /** Human-readable name for the scene */
+    name: string;
+    /** Duration of the scene in milliseconds */
+    duration: number;
+    /** Array of compiled layer objects with instances */
+    layers: CompiledLayer[];
+    /** Compiled audio tracks for this scene */
+    audioTracks: CompiledAudioTrack[];
+    /** Start time of this scene in the global timeline */
+    startTime: number;
+    /** End time of this scene in the global timeline */
+    endTime: number;
+}
+interface CompiledLayer {
+    /** Unique identifier for the layer */
+    id: string;
+    /** Layer type for renderer selection */
+    type: string;
+    /** Z-index for rendering order */
+    zIndex: number;
+    /** Instantiated layer object ready for rendering */
+    instance: ICinematicLayer;
+    /** Precompiled animation tracks for optimal performance */
+    animations: CompiledAnimationTrack[];
+    /** Initial configuration values */
+    initialConfig: Record<string, any>;
+    /** Whether this layer is currently active */
+    active: boolean;
+}
+interface CompiledAnimationTrack {
+    /** CSS property path being animated */
+    property: string;
+    /** Animation start time in milliseconds */
+    startMs: number;
+    /** Animation end time in milliseconds */
+    endMs: number;
+    /** Precompiled interpolation function for maximum performance */
+    interpolate: (progress: number) => any;
+    /** Whether the animation loops */
+    loop: boolean;
+    /** Whether the animation reverses on each loop */
+    yoyo: boolean;
+    /** Original easing type for debugging */
+    easingType: EasingType;
+    /** Current loop iteration (for looped animations) */
+    currentLoop: number;
+    /** Whether animation is currently in reverse (for yoyo) */
+    isReverse: boolean;
+}
+interface CompiledAudioTrack {
+    /** Unique identifier for the audio track */
+    id: string;
+    /** Type of audio content */
+    type: AudioTrackType;
+    /** Loaded asset reference */
+    asset: Asset;
+    /** Start time in milliseconds */
+    startMs: number;
+    /** End time in milliseconds */
+    endMs: number;
+    /** Volume level (0-1) */
+    volume: number;
+    /** Fade in duration in milliseconds */
+    fadeIn: number;
+    /** Fade out duration in milliseconds */
+    fadeOut: number;
+    /** Whether to loop the audio */
+    loop: boolean;
+    /** Audio context node for Web Audio API */
+    audioNode?: AudioNode;
+    /** HTML audio element for fallback */
+    audioElement?: HTMLAudioElement;
+}
+interface CompiledTransition {
+    /** Type of transition effect */
+    type: TransitionType;
+    /** Duration of the transition in milliseconds */
+    duration: number;
+    /** Precompiled easing function */
+    easingFunction: (t: number) => number;
+    /** Transition-specific configuration */
+    config: Record<string, any>;
+    /** Precompiled transition function for performance */
+    execute: (progress: number, fromElement: HTMLElement, toElement: HTMLElement) => void;
+}
+/** Animation interpolation function signature */
+type InterpolationFunction = (progress: number) => any;
+/** Easing function signature */
+type EasingFunction = (t: number) => number;
+/** Transition execution function signature */
+type TransitionFunction = (progress: number, fromElement: HTMLElement, toElement: HTMLElement) => void;
+/** Compilation context for tracking state during parsing */
+interface CompilationContext {
+    /** Current schema version being processed */
+    schemaVersion: string;
+    /** Asset loading promises for dependency tracking */
+    assetPromises: Map<string, Promise<Asset>>;
+    /** Layer type registry for validation */
+    layerTypes: Set<string>;
+    /** Compilation warnings and errors */
+    diagnostics: CompilationDiagnostic[];
+    /** Performance optimization flags */
+    optimizations: CompilationOptimizations;
+}
+/** Compilation diagnostic information */
+interface CompilationDiagnostic {
+    /** Severity level */
+    level: 'error' | 'warning' | 'info';
+    /** Human-readable message */
+    message: string;
+    /** Location in the source specification */
+    location?: {
+        path: string;
+        line?: number;
+        column?: number;
+    };
+    /** Error code for programmatic handling */
+    code?: string;
+}
+/** Compilation optimization settings */
+interface CompilationOptimizations {
+    /** Precompile animation tracks */
+    precompileAnimations: boolean;
+    /** Optimize asset loading order */
+    optimizeAssetLoading: boolean;
+    /** Enable object pooling for particles */
+    enableObjectPooling: boolean;
+    /** Minimize DOM manipulations */
+    minimizeDOMUpdates: boolean;
+    /** Use Web Workers for heavy computations */
+    useWebWorkers: boolean;
+}
+
+/**
+ * Layer Registry for managing layer types and instances
+ * Supports both built-in layer types and custom layer plugins
+ */
+
+type LayerFactory = (id: string, config: Record<string, any>) => ICinematicLayer;
+declare class LayerRegistry {
+    private layerTypes;
+    private static instance;
+    constructor();
+    /**
+     * Get the global layer registry instance
+     */
+    static getInstance(): LayerRegistry;
+    /**
+     * Register a custom layer type with a factory function
+     */
+    registerLayerType(type: string, factory: LayerFactory): void;
+    /**
+     * Create a layer instance of the specified type
+     */
+    createLayer(type: string, id: string, config: Record<string, any>): ICinematicLayer;
+    /**
+     * Check if a layer type is registered
+     */
+    hasLayerType(type: string): boolean;
+    /**
+     * Get all registered layer type names
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Get built-in layer types (DOM and Canvas2D)
+     */
+    getBuiltInTypes(): {
+        dom: string[];
+        canvas2d: string[];
+    };
+    /**
+     * Check if a layer type is a built-in type
+     */
+    isBuiltInType(type: string): boolean;
+    /**
+     * Get custom (non-built-in) layer types
+     */
+    getCustomTypes(): string[];
+    /**
+     * Unregister a layer type (useful for testing or dynamic plugin management)
+     */
+    unregisterLayerType(type: string): boolean;
+    /**
+     * Clear all custom layer types (keeps built-in types)
+     */
+    clearCustomTypes(): void;
+    /**
+     * Register all built-in layer types
+     */
+    private registerBuiltInLayers;
+}
+
+/**
+ * Built-in layer type implementations
+ * DOM layers fully implemented for Task 7.1
+ * Canvas2D layers will be completed in Task 8.1
+ */
+
+/**
+ * Base class for built-in layers with common functionality
+ */
+declare abstract class BaseLayer implements ICinematicLayer {
+    readonly id: string;
+    readonly type: string;
+    readonly zIndex: number;
+    protected config: Record<string, any>;
+    protected mounted: boolean;
+    constructor(id: string, type: string, config: Record<string, any>);
+    abstract mount(ctx: LayerMountContext): void;
+    abstract update(ctx: FrameContext$1): void;
+    destroy(): void;
+    setVisible(_visible: boolean): void;
+    setOpacity(_opacity: number): void;
+    resize(_width: number, _height: number): void;
+}
+declare class GradientLayer extends BaseLayer {
+    private element?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class ImageLayer extends BaseLayer {
+    private element?;
+    private img?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class TextBlockLayer extends BaseLayer {
+    private element?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class VignetteLayer extends BaseLayer {
+    private element?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class GlowOrbLayer extends BaseLayer {
+    private element?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class NoiseOverlayLayer extends BaseLayer {
+    private element?;
+    private canvas?;
+    private ctx?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    private generateNoise;
+    resize(_width: number, _height: number): void;
+    destroy(): void;
+}
+declare class ParticlesLayer extends BaseLayer {
+    private canvas?;
+    private ctx?;
+    private particles;
+    private canvas2DRenderer?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class StarfieldLayer extends BaseLayer {
+    private canvas?;
+    private ctx?;
+    private stars;
+    private canvas2DRenderer?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class DustLayer extends BaseLayer {
+    private canvas?;
+    private ctx?;
+    private dustParticles;
+    private canvas2DRenderer?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    destroy(): void;
+}
+declare class NebulaNoiseLayer extends BaseLayer {
+    private canvas?;
+    private ctx?;
+    private noiseData?;
+    private canvas2DRenderer?;
+    constructor(id: string, config: Record<string, any>);
+    mount(ctx: LayerMountContext): void;
+    update(ctx: FrameContext$1): void;
+    private perlinNoise;
+    private noise;
+    private hexToRgb;
+    destroy(): void;
+}
+
+/**
+ * Animation track compilation system
+ *
+ * Provides high-performance animation compilation with comprehensive easing functions,
+ * interpolation for different value types, and support for loops and yoyo effects.
+ * All animations are precompiled at parse time to avoid per-frame calculations.
+ *
+ * Requirements: 6.1, 6.2, 6.3, 6.4, 6.5
+ */
+
+/**
+ * Animation compilation system with optimized easing and interpolation functions
+ */
+declare class AnimationCompiler {
+    /**
+     * Compiles an animation track specification into an optimized runtime track
+     *
+     * @param track - Animation track specification to compile
+     * @returns Compiled animation track with precompiled interpolation function
+     */
+    static compileTrack(track: AnimationTrackSpec): CompiledAnimationTrack;
+    /**
+     * Compiles an easing function from string specification to optimized function
+     *
+     * @param easing - Easing type or cubic-bezier specification
+     * @returns Optimized easing function that maps [0,1] to [0,1]
+     */
+    static compileEasing(easing: EasingType): EasingFunction;
+    /**
+     * Compiles an interpolation function for animating between two values
+     *
+     * @param from - Starting value
+     * @param to - Ending value
+     * @param easingFunction - Easing function to apply
+     * @returns Optimized interpolation function
+     */
+    static compileInterpolation(from: AnimationValue, to: AnimationValue, easingFunction: EasingFunction): InterpolationFunction;
+    /**
+     * Creates a cubic-bezier easing function with the given control points
+     */
+    private static cubicBezier;
+    /**
+     * Parses and compiles a cubic-bezier string specification
+     */
+    private static compileCubicBezier;
+    /**
+     * Creates a back easing function with overshoot
+     */
+    private static backEasing;
+    /**
+     * Creates an elastic easing function with oscillation
+     */
+    private static elasticEasing;
+    /**
+     * Bounce easing out function
+     */
+    private static bounceOut;
+    /**
+     * Determines the type of an animation value
+     */
+    private static getValueType;
+    /**
+     * Compiles number interpolation with optimized performance
+     */
+    private static compileNumberInterpolation;
+    /**
+     * Compiles string interpolation with CSS value support
+     */
+    private static compileStringInterpolation;
+    /**
+     * Compiles boolean interpolation (discrete transition)
+     */
+    private static compileBooleanInterpolation;
+    /**
+     * Compiles object interpolation for complex values
+     */
+    private static compileObjectInterpolation;
+}
+
+/**
+ * DOM-based rendering backend
+ * Optimized for 60-120fps performance using CSS transforms and will-change properties
+ */
+
+declare class DOMRenderer extends RenderBackend {
+    private domContainer;
+    private layerElements;
+    private initialized;
+    initialize(): void;
+    render(layers: ICinematicLayer[], context: FrameContext$1): void;
+    resize(width: number, height: number): void;
+    destroy(): void;
+    /**
+     * Create a DOM element for a layer with performance optimizations
+     */
+    createLayerElement(layerId: string, zIndex: number): HTMLElement;
+    /**
+     * Remove a layer element from the DOM
+     */
+    removeLayerElement(layerId: string): void;
+    /**
+     * Get the DOM container for layers
+     */
+    getDOMContainer(): HTMLElement;
+    /**
+     * Get a layer element by ID
+     */
+    getLayerElement(layerId: string): HTMLElement | undefined;
+}
+
+/**
+ * Canvas2D-based rendering backend with devicePixelRatio scaling and object pooling
+ *
+ * This renderer handles particles, noise, and starfields with high performance
+ * through object pooling and efficient canvas operations.
+ *
+ * Requirements: 4.2, 4.4 - Canvas2D rendering with devicePixelRatio and object pooling
+ */
+
+/**
+ * Canvas2D renderer with devicePixelRatio scaling and performance monitoring
+ */
+declare class Canvas2DRenderer extends RenderBackend {
+    private canvas;
+    private ctx;
+    private devicePixelRatio;
+    private width;
+    private height;
+    private canvasWidth;
+    private canvasHeight;
+    private particlePool;
+    private activeParticles;
+    private performanceMetrics;
+    private lastFrameTime;
+    private frameCount;
+    private fpsUpdateTime;
+    constructor(container: HTMLElement);
+    initialize(): void;
+    render(layers: ICinematicLayer[], context: FrameContext$1): void;
+    private renderParticleLayer;
+    private renderNoiseLayer;
+    private initializeParticle;
+    private drawStar;
+    private simpleNoise;
+    private updatePerformanceMetrics;
+    resize(width: number, height: number): void;
+    destroy(): void;
+    /**
+     * Get current performance metrics
+     */
+    getPerformanceMetrics(): PerformanceMetrics;
+    /**
+     * Create a canvas for a specific layer (used by layers that need their own canvas)
+     */
+    createLayerCanvas(width: number, height: number): HTMLCanvasElement;
+}
+
+/**
+ * Audio system with WebAudio API and HTMLAudio fallback
+ *
+ * This system handles audio playback for cinematic experiences with support for:
+ * - WebAudio API for precise timing and effects
+ * - HTMLAudio fallback for compatibility
+ * - Multiple audio track types (voiceover, ambience, transition, music, sfx)
+ * - Fade in/out effects and volume control
+ * - Audio-visual timeline synchronization
+ * - Graceful handling of autoplay restrictions
+ *
+ * Requirements: 7.1, 7.2, 7.3, 7.4, 7.5
+ */
+
+interface AudioSystemConfig {
+    /** Preferred audio context sample rate */
+    sampleRate?: number;
+    /** Master volume (0-1) */
+    masterVolume?: number;
+    /** Whether to use WebAudio API when available */
+    preferWebAudio?: boolean;
+    /** Maximum number of concurrent audio tracks */
+    maxConcurrentTracks?: number;
+    /** Default fade duration in milliseconds */
+    defaultFadeDuration?: number;
+}
+interface AudioSystemEvents {
+    'track-started': (trackId: string) => void;
+    'track-ended': (trackId: string) => void;
+    'track-error': (trackId: string, error: Error) => void;
+    'context-suspended': () => void;
+    'context-resumed': () => void;
+    'autoplay-blocked': (trackId: string) => void;
+}
+declare class AudioSystem {
+    private _config;
+    private _eventListeners;
+    private _audioContext;
+    private _masterGainNode;
+    private _activeTracks;
+    private _compiledTracks;
+    private _isInitialized;
+    private _currentTime;
+    private _isPlaying;
+    private _userInteracted;
+    constructor(config?: AudioSystemConfig);
+    /**
+     * Initialize the audio system
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load and compile audio tracks for a scene
+     */
+    loadTracks(tracks: CompiledAudioTrack[]): Promise<void>;
+    /**
+     * Start playback of the audio system
+     */
+    play(): void;
+    /**
+     * Pause playback of all audio tracks
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset all tracks
+     */
+    stop(): void;
+    /**
+     * Update audio system with current timeline position
+     */
+    update(timeMs: number): void;
+    /**
+     * Seek to a specific time position
+     */
+    seek(timeMs: number): void;
+    /**
+     * Set master volume
+     */
+    setMasterVolume(volume: number): void;
+    /**
+     * Get current master volume
+     */
+    getMasterVolume(): number;
+    /**
+     * Check if audio context is available and active
+     */
+    isWebAudioAvailable(): boolean;
+    /**
+     * Get current audio context state
+     */
+    getAudioContextState(): AudioContextState | null;
+    /**
+     * Get active track count
+     */
+    getActiveTrackCount(): number;
+    /**
+     * Destroy the audio system and clean up resources
+     */
+    destroy(): void;
+    /**
+     * Add event listener
+     */
+    on<K extends keyof AudioSystemEvents>(event: K, callback: AudioSystemEvents[K]): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof AudioSystemEvents>(event: K, callback: AudioSystemEvents[K]): void;
+    private _initializeWebAudio;
+    private _createHTMLAudioElement;
+    private _startTrack;
+    private _startWebAudioTrack;
+    private _startHTMLAudioTrack;
+    private _pauseTrack;
+    private _stopTrack;
+    private _forceStopTrack;
+    private _updateTrack;
+    private _fadeHTMLAudio;
+    private _setupUserInteractionDetection;
+    private _emit;
+}
+
+/**
+ * Adaptive quality system for performance optimization
+ *
+ * This system monitors performance metrics and automatically adjusts
+ * rendering quality to maintain target frame rates while respecting
+ * user preferences and device capabilities.
+ *
+ * Requirements: 8.1, 8.2, 8.3, 8.4, 8.5
+ */
+
+declare class QualitySystem {
+    private currentQuality;
+    private currentSettings;
+    private deviceCapabilities;
+    private config;
+    private performanceHistory;
+    private badFrameCount;
+    private goodFrameCount;
+    private lastQualityChange;
+    private eventCallbacks;
+    constructor(config?: Partial<QualitySystemConfig>);
+    setQuality(level: QualityLevel$1): void;
+    getCurrentQuality(): QualityLevel$1;
+    getCurrentSettings(): QualitySettings;
+    getDeviceCapabilities(): DeviceCapabilities;
+    updatePerformanceMetrics(metrics: PerformanceMetrics): void;
+    addEventListener(callback: (event: PerformanceEvent) => void): void;
+    removeEventListener(callback: (event: PerformanceEvent) => void): void;
+    private getQualitySettings;
+    private getQualityPresets;
+    private detectDeviceCapabilities;
+    private detectHardwareAcceleration;
+    private detectMobile;
+    private detectConnectionType;
+    private determineInitialQuality;
+    private determineAutoQuality;
+    private evaluatePerformanceAndAdjust;
+    private reduceQuality;
+    private increaseQuality;
+    private checkPerformanceWarnings;
+    private getRecentMetrics;
+    private getLatestMetrics;
+    private emitEvent;
+}
+
+/**
+ * JSON Specification Parser with Zod validation
+ *
+ * Provides comprehensive JSON schema validation, default value application,
+ * and descriptive error message generation for cinematic specifications.
+ * Supports schema versioning for backward compatibility.
+ *
+ * Requirements: 3.1, 3.2, 3.4, 3.5
+ */
+
+/**
+ * SpecParser class with comprehensive Zod validation and compilation
+ */
+declare class SpecParser {
+    /**
+     * Validates and parses a raw JSON specification into a validated CinematicSpec
+     *
+     * @param spec - Raw JSON specification to validate
+     * @returns Validated CinematicSpec with applied defaults
+     * @throws ZodError with descriptive validation messages
+     */
+    static validate(spec: unknown): CinematicSpec;
+    /**
+     * Compiles a validated CinematicSpec into an optimized CompiledSpec
+     *
+     * @param spec - Validated CinematicSpec to compile
+     * @returns CompiledSpec with precompiled animations and optimized runtime structures
+     */
+    static parse(spec: CinematicSpec): CompiledSpec;
+    /**
+     * Validates specification based on schema version
+     */
+    private static validateByVersion;
+    /**
+     * Compiles asset definitions into runtime assets
+     */
+    private static compileAssets;
+    /**
+     * Compiles scene definitions into runtime scenes
+     */
+    private static compileScenes;
+    /**
+     * Compiles layer specifications into runtime layers
+     */
+    private static compileLayers;
+    /**
+     * Compiles animation tracks into optimized runtime animations
+     */
+    private static compileAnimationTracks;
+    /**
+     * Compiles audio tracks into runtime audio objects
+     */
+    private static compileAudioTracks;
+    /**
+     * Compiles event definitions into runtime events
+     */
+    private static compileEvents;
+    /**
+     * Compiles transition specifications into runtime transitions
+     */
+    private static compileTransitions;
+    /**
+     * Formats Zod validation errors into human-readable messages
+     */
+    private static formatZodError;
+}
+
+/**
+ * Frame scheduling system using requestAnimationFrame with FPS monitoring
+ * and performance tracking for adaptive quality management.
+ *
+ * Requirements: 2.5, 8.1, 8.2, 8.3
+ */
+
+interface FrameContext {
+    /** Time elapsed since last frame in milliseconds */
+    deltaMs: number;
+    /** Current timestamp from performance.now() */
+    currentTime: number;
+    /** Current frames per second */
+    fps: number;
+    /** Frame number since start */
+    frameNumber: number;
+    /** Current performance metrics */
+    metrics: PerformanceMetrics;
+}
+interface SchedulerOptions {
+    /** Target FPS (default: 60) */
+    targetFps?: number;
+    /** FPS monitoring window size in frames (default: 60) */
+    fpsWindowSize?: number;
+    /** Performance monitoring interval in milliseconds (default: 1000) */
+    monitoringInterval?: number;
+    /** Whether to enable adaptive quality (default: true) */
+    enableAdaptiveQuality?: boolean;
+}
+declare class Scheduler {
+    private isRunning;
+    private animationFrameId;
+    private lastFrameTime;
+    private frameCallbacks;
+    private frameNumber;
+    private frameTimes;
+    private currentFps;
+    private lastMonitoringTime;
+    private performanceMetrics;
+    private options;
+    private qualityChangeCallbacks;
+    constructor(options?: SchedulerOptions);
+    start(): void;
+    stop(): void;
+    addFrameCallback(callback: (context: FrameContext) => void): void;
+    removeFrameCallback(callback: (context: FrameContext) => void): void;
+    addQualityChangeCallback(callback: (metrics: PerformanceMetrics) => void): void;
+    removeQualityChangeCallback(callback: (metrics: PerformanceMetrics) => void): void;
+    getCurrentFps(): number;
+    getPerformanceMetrics(): PerformanceMetrics;
+    updateMetrics(updates: Partial<PerformanceMetrics>): void;
+    private scheduleFrame;
+    private updateFpsTracking;
+    private performPerformanceCheck;
+    /** Get average frame time over the monitoring window */
+    getAverageFrameTime(): number;
+    /** Get frame time variance (measure of frame time consistency) */
+    getFrameTimeVariance(): number;
+    /** Check if performance is stable (low variance) */
+    isPerformanceStable(): boolean;
+    /** Get performance grade (A, B, C, D, F) */
+    getPerformanceGrade(): string;
+}
+
+/**
+ * Debug overlay system for cinematicRenderer2D
+ *
+ * Provides real-time debugging information including FPS counter,
+ * timeline info, layer status, and performance metrics.
+ */
+
+interface DebugInfo {
+    fps: number;
+    currentTime: number;
+    duration: number;
+    currentEvent: string | null;
+    currentScene: string | null;
+    quality: QualityLevel$1;
+    activeLayers: number;
+    activeParticles: number;
+    domNodes: number;
+    drawCalls: number;
+    memoryUsage?: number;
+    isPlaying: boolean;
+    isPaused: boolean;
+}
+interface DebugOverlayOptions {
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    opacity?: number;
+    fontSize?: number;
+    updateInterval?: number;
+    showPerformanceGraph?: boolean;
+    maxGraphPoints?: number;
+}
+declare class DebugOverlay {
+    private renderer;
+    private container;
+    private overlayElement;
+    private options;
+    private updateTimer;
+    private isVisible;
+    private fpsHistory;
+    private frameTimeHistory;
+    private lastUpdateTime;
+    constructor(renderer: CinematicRenderer2D, container: HTMLElement, options?: DebugOverlayOptions);
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    destroy(): void;
+    private createOverlay;
+    private getOverlayStyles;
+    private setupEventListeners;
+    private startUpdating;
+    private stopUpdating;
+    private updateDisplay;
+    private gatherDebugInfo;
+    private generateDebugHTML;
+    private generatePerformanceGraph;
+    private updatePerformanceHistory;
+    private getFpsColor;
+    private getQualityColor;
+    private getTargetFps;
+    private getMemoryUsage;
+}
+
+/**
+ * Utility Types for cinematicRenderer2D
+ *
+ * Common utility types used throughout the cinematic rendering system.
+ * These provide type safety and consistency across all modules.
+ */
+/** Viewport dimensions and properties */
+interface Viewport {
+    /** Viewport width in pixels */
+    width: number;
+    /** Viewport height in pixels */
+    height: number;
+    /** Device pixel ratio */
+    devicePixelRatio: number;
+    /** Aspect ratio (width / height) */
+    aspectRatio: number;
+}
+/** 2D point coordinates */
+interface Point2D {
+    x: number;
+    y: number;
+}
+/** 2D vector with magnitude and direction */
+interface Vector2D extends Point2D {
+    /** Vector magnitude */
+    magnitude?: number;
+    /** Vector angle in radians */
+    angle?: number;
+}
+/** Rectangle bounds */
+interface Rectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Color representation in various formats */
+interface Color {
+    /** Red component (0-255) */
+    r: number;
+    /** Green component (0-255) */
+    g: number;
+    /** Blue component (0-255) */
+    b: number;
+    /** Alpha component (0-1) */
+    a?: number;
+}
+/** HSL color representation */
+interface HSLColor {
+    /** Hue (0-360) */
+    h: number;
+    /** Saturation (0-100) */
+    s: number;
+    /** Lightness (0-100) */
+    l: number;
+    /** Alpha component (0-1) */
+    a?: number;
+}
+/** Time-based value for animations */
+interface TimeValue {
+    /** Value at this time */
+    value: any;
+    /** Time in milliseconds */
+    time: number;
+    /** Easing function to next keyframe */
+    easing?: string;
+}
+/** Event listener callback signature */
+type EventCallback<T = any> = (data: T) => void;
+/** Disposable resource interface */
+interface Disposable {
+    /** Clean up resources */
+    dispose(): void;
+    /** Whether the resource has been disposed */
+    isDisposed: boolean;
+}
+/** Observable pattern for event emission */
+interface Observable<T> {
+    /** Subscribe to events */
+    subscribe(callback: EventCallback<T>): () => void;
+    /** Unsubscribe from events */
+    unsubscribe(callback: EventCallback<T>): void;
+    /** Emit an event */
+    emit(data: T): void;
+}
+/** Deep partial type for configuration objects */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/** Make all properties required recursively */
+type DeepRequired<T> = {
+    [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
+};
+
+/**
+ * cinematicRenderer2D - High-performance, framework-agnostic cinematic rendering library
+ *
+ * This library renders cinematic experiences from JSON specifications targeting 60-120fps performance.
+ * It provides DOM, Canvas2D, and future WebGL rendering backends with adaptive quality systems.
+ */
+
+declare const VERSION = "0.1.0";
+
+export { AnimationCompiler, type CompiledAnimationTrack as AnimationTrack, type AnimationTrackSpec, type AnimationValue, type AnimationValueObject, type Asset, type AssetCacheConfig, type AssetData, type AssetDefinition$1 as AssetDefinition, type AssetLoadOptions, type AssetLoadProgress, AssetManager, type AssetMetadata$1 as AssetMetadata, type AssetPriority, type AssetType$1 as AssetType, AudioSystem, type AudioTrackSpec, type AudioTrackType, Canvas2DRenderer, type CinematicEvent, CinematicRenderer2D, type CinematicScene, type CinematicSpec, type Color, type CompilationContext, type CompilationDiagnostic, type CompilationOptimizations, type CompiledAnimationTrack, type CompiledAudioTrack, type CompiledEvent, type CompiledLayer, type CompiledScene, type CompiledSpec, type CompiledTransition, DOMRenderer, type DebugInfo, DebugOverlay, type DebugOverlayOptions, type DeepPartial, type DeepRequired, type DeviceCapabilities, type Disposable, DustLayer, type EasingFunction, type EasingType, type EngineConfig, type EventCallback, type FrameContext$1 as FrameContext, GlowOrbLayer, GradientLayer, type HSLColor, type ICinematicLayer, type ICinematicRenderer2D, ImageLayer, type InterpolationFunction, type LayerConfig, type LayerFactory, type LayerMountContext, LayerRegistry, type LayerSpec, type LayerType, NebulaNoiseLayer, NoiseOverlayLayer, type Observable, ParticlesLayer, type PerformanceEvent, type PerformanceMetrics, type PlaybackState, type Point2D, QUALITY_PRESETS, type QualityLevel, type QualitySettings, QualitySystem, type QualitySystemConfig, type Rectangle, RenderBackend, Scheduler, SpecParser, StarfieldLayer, TextBlockLayer, type TimeValue, type TransformConfig, type TransitionConfig, type TransitionFunction, type TransitionSpec, type TransitionType, VERSION, type Vector2D, type Viewport, VignetteLayer };