cinematic-renderer2d 0.1.0

package/dist/angular.d.cts

@@ -0,0 +1,577 @@
+import { OnInit, OnDestroy, OnChanges, ElementRef, EventEmitter, NgZone, SimpleChanges } from '@angular/core';
+
+/**
+ * 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';
+}
+
+/**
+ * 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[];
+}
+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 {
+    /** 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?: AssetMetadata;
+}
+/** Supported asset types */
+type AssetType = 'image' | 'video' | 'audio' | 'font' | 'json' | 'binary';
+/** 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 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;
+}
+
+/**
+ * Angular adapter for cinematicRenderer2D
+ *
+ * Provides a CinematicPlayerComponent Angular component that wraps the core engine
+ * with Angular-specific lifecycle management and event handling.
+ *
+ * Requirements: 10.2, 10.3, 10.4, 10.5 - Angular integration with proper lifecycle
+ */
+
+interface CinematicPlayerEvents {
+    ready: void;
+    play: {
+        previousState: PlaybackState;
+        currentTime: number;
+    };
+    pause: {
+        previousState: PlaybackState;
+        currentTime: number;
+    };
+    stop: {
+        previousState: PlaybackState;
+    };
+    seek: {
+        previousTime: number;
+        currentTime: number;
+        currentEvent: string | null;
+        currentScene: string | null;
+    };
+    eventChange: {
+        eventId: string;
+        eventName: string;
+        currentTime: number;
+    };
+    sceneChange: {
+        sceneId: string;
+        sceneName: string;
+        currentTime: number;
+    };
+    qualityChange: {
+        previousQuality: QualityLevel$1;
+        currentQuality: QualityLevel$1;
+        metrics?: any;
+    };
+    resize: {
+        width: number;
+        height: number;
+    };
+    frame: {
+        currentTime: number;
+        fps: number;
+        deltaMs: number;
+        currentEvent: string | null;
+        currentScene: string | null;
+    };
+    stateChange: {
+        previousState: PlaybackState;
+        currentState: PlaybackState;
+    };
+    ended: void;
+    error: Error;
+    loading: void;
+    destroy: {
+        previousState: PlaybackState;
+    };
+    audioError: {
+        trackId: string;
+        error: Error;
+    };
+    autoplayBlocked: {
+        trackId: string;
+    };
+}
+/**
+ * CinematicPlayerComponent Angular Component
+ *
+ * An Angular wrapper for the CinematicRenderer2D engine that handles:
+ * - Angular lifecycle integration (ngOnInit/ngOnDestroy)
+ * - Input/Output bindings for spec and events
+ * - Event forwarding to Angular event system
+ * - Automatic cleanup on component destruction
+ */
+declare class CinematicPlayerComponent implements OnInit, OnDestroy, OnChanges {
+    private ngZone;
+    containerRef: ElementRef<HTMLDivElement>;
+    spec: CinematicSpec;
+    autoplay: boolean;
+    quality?: QualityLevel$1;
+    debug: boolean;
+    containerClass?: string;
+    containerStyle?: {
+        [key: string]: any;
+    };
+    ready: EventEmitter<void>;
+    play: EventEmitter<{
+        previousState: PlaybackState;
+        currentTime: number;
+    }>;
+    pause: EventEmitter<{
+        previousState: PlaybackState;
+        currentTime: number;
+    }>;
+    stop: EventEmitter<{
+        previousState: PlaybackState;
+    }>;
+    seek: EventEmitter<{
+        previousTime: number;
+        currentTime: number;
+        currentEvent: string | null;
+        currentScene: string | null;
+    }>;
+    eventChange: EventEmitter<{
+        eventId: string;
+        eventName: string;
+        currentTime: number;
+    }>;
+    sceneChange: EventEmitter<{
+        sceneId: string;
+        sceneName: string;
+        currentTime: number;
+    }>;
+    qualityChange: EventEmitter<{
+        previousQuality: QualityLevel$1;
+        currentQuality: QualityLevel$1;
+        metrics?: any;
+    }>;
+    resize: EventEmitter<{
+        width: number;
+        height: number;
+    }>;
+    frame: EventEmitter<{
+        currentTime: number;
+        fps: number;
+        deltaMs: number;
+        currentEvent: string | null;
+        currentScene: string | null;
+    }>;
+    stateChange: EventEmitter<{
+        previousState: PlaybackState;
+        currentState: PlaybackState;
+    }>;
+    ended: EventEmitter<void>;
+    error: EventEmitter<Error>;
+    loading: EventEmitter<void>;
+    destroy: EventEmitter<{
+        previousState: PlaybackState;
+    }>;
+    audioError: EventEmitter<{
+        trackId: string;
+        error: Error;
+    }>;
+    autoplayBlocked: EventEmitter<{
+        trackId: string;
+    }>;
+    private engine;
+    private initialized;
+    constructor(ngZone: NgZone);
+    ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    playEngine(): void;
+    pauseEngine(): void;
+    stopEngine(): void;
+    seekEngine(timeMs: number): void;
+    goToEvent(eventId: string): void;
+    goToScene(sceneId: string): void;
+    setQuality(level: QualityLevel$1): void;
+    resizeEngine(width: number, height: number): 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(): any;
+    getQualitySettings(): any;
+    getDeviceCapabilities(): any;
+    setMasterVolume(volume: number): void;
+    getMasterVolume(): number;
+    isWebAudioAvailable(): boolean;
+    getActiveAudioTrackCount(): number;
+    getEngine(): CinematicRenderer2D | null;
+    private initializeEngine;
+    private setupEventListeners;
+    private destroyEngine;
+}
+
+export { type CinematicEvent, CinematicPlayerComponent, type CinematicPlayerEvents, type CinematicScene, type CinematicSpec, type LayerSpec, type LayerType, type PlaybackState, type QualityLevel };