/**
 * Defines the type of property that will be animated.
 * @type {AnimationType}
 * - position: Animates x, y, z coordinates
 * - rotation: Animates rotation angles (euler or quaternion)
 * - scale: Animates scale factors
 * - color: Animates color values (RGB/RGBA)
 * - opacity: Animates transparency/alpha channel
 * - custom: User-defined animation properties
 */
export type AnimationType = 'position' | 'rotation' | 'scale' | 'color' | 'opacity' | 'custom';
/**
 * Defines how the animation behaves when it reaches the end.
 * @type {LoopMode}
 * - none: Animation plays once and stops
 * - repeat: Animation restarts from the beginning when it ends
 * - pingpong: Animation reverses direction when it reaches either end
 */
export type LoopMode = 'none' | 'repeat' | 'pingpong';
/**
 * Easing functions that control the rate of change of the animation over time.
 * @type {EasingType}
 * - linear: Constant rate of change
 * - easeIn*: Slow start, accelerates towards the end
 * - easeOut*: Fast start, decelerates towards the end
 * - easeInOut*: Slow start and end with acceleration in the middle
 * - Quad: Power of 2 curve
 * - Cubic: Power of 3 curve
 * - Quart: Power of 4 curve
 * - Expo: Exponential curve
 * - Back: Overshoots then returns
 * - Elastic: Spring-like effect
 * - Bounce: Bouncing effect at the end
 */
export type EasingType = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeInElastic' | 'easeOutElastic' | 'easeInOutElastic' | 'easeInBounce' | 'easeOutBounce' | 'easeInOutBounce';
/**
 * Represents a single keyframe in an animation curve.
 * @interface Keyframe
 * @property {number} time - The time position of this keyframe in seconds
 * @property {any} value - The value at this keyframe (depends on animation type)
 * @property {EasingType} [easing] - Easing function to use from this keyframe to the next
 * @property {number} [tangentIn] - Incoming tangent for cubic interpolation (Bezier curves)
 * @property {number} [tangentOut] - Outgoing tangent for cubic interpolation (Bezier curves)
 */
export interface Keyframe {
    time: number;
    value: any;
    easing?: EasingType;
    tangentIn?: number;
    tangentOut?: number;
}
/**
 * Defines an animation curve with multiple keyframes and extrapolation behavior.
 * @interface AnimationCurve
 * @property {Keyframe[]} keyframes - Array of keyframes defining the animation curve
 * @property {string} [preInfinity] - How to extrapolate before the first keyframe:
 *   - constant: Hold the first value
 *   - linear: Continue linearly based on first two keyframes
 *   - cycle: Repeat the entire animation
 *   - cycleOffset: Repeat with accumulated offset
 *   - oscillate: Ping-pong repeat
 * @property {string} [postInfinity] - How to extrapolate after the last keyframe (same options as preInfinity)
 */
export interface AnimationCurve {
    keyframes: Keyframe[];
    preInfinity?: 'constant' | 'linear' | 'cycle' | 'cycleOffset' | 'oscillate';
    postInfinity?: 'constant' | 'linear' | 'cycle' | 'cycleOffset' | 'oscillate';
}
/**
 * Represents a single animation action that animates a specific property over time.
 * @interface AnimationAction
 * @property {string} id - Unique identifier for this action
 * @property {string} name - Human-readable name for the action
 * @property {AnimationType} type - Type of property being animated
 * @property {string} target - ID or reference to the target object
 * @property {string} [path] - Optional path to nested property (e.g., "material.color")
 * @property {string} property - Specific property to animate (e.g., "x", "opacity")
 * @property {AnimationCurve} [curve] - Animation curve with keyframes (advanced)
 * @property {any} [from] - Starting value (simple animations)
 * @property {any} [to] - Ending value (simple animations)
 * @property {number} duration - Duration of the animation in seconds
 * @property {number} startTime - When this action starts relative to the clip
 * @property {number} endTime - When this action ends relative to the clip
 * @property {EasingType} [easing] - Easing function for simple from/to animations
 * @property {LoopMode} [loop] - How the animation loops
 * @property {number} [loopCount] - Number of times to loop (internal state)
 * @property {number} [weight] - Influence weight when blending with other actions (0-1)
 * @property {boolean} enabled - Whether this action is active
 * @property {string} [blendMode] - How to combine with other animations:
 *   - replace: Overwrite previous values
 *   - additive: Add to previous values
 *   - multiply: Multiply with previous values
 */
export interface AnimationAction {
    id: string;
    name: string;
    type: AnimationType;
    target: string;
    path?: string;
    property: string;
    curve?: AnimationCurve;
    from?: any;
    to?: any;
    duration: number;
    startTime: number;
    endTime: number;
    easing?: EasingType;
    loop?: LoopMode;
    /** action can have internal state */
    loopCount?: number;
    weight?: number;
    enabled: boolean;
    blendMode?: 'replace' | 'additive' | 'multiply';
}
/**
 * Container for multiple animation actions that play together.
 * @interface AnimationClip
 * @property {string} id - Unique identifier for the clip
 * @property {string} name - Human-readable name
 * @property {number} duration - Total duration of the clip in seconds
 * @property {number} fps - Frames per second for the clip
 * @property {AnimationAction[]} actions - All animation actions in this clip
 * @property {AnimationMarker[]} [markers] - Optional timeline markers for events
 * @property {Record<string, any>} [metadata] - Additional custom data
 */
export interface AnimationClip {
    id: string;
    name: string;
    duration: number;
    fps: number;
    actions: AnimationAction[];
    markers?: AnimationMarker[];
    metadata?: Record<string, any>;
}
/**
 * Timeline marker for triggering events or marking important points.
 * @interface AnimationMarker
 * @property {string} id - Unique identifier
 * @property {string} name - Marker label
 * @property {number} time - Time position in seconds
 * @property {string} [color] - Visual color for UI display
 * @property {any} [data] - Custom data payload for the marker
 */
export interface AnimationMarker {
    id: string;
    name: string;
    time: number;
    color?: string;
    data?: any;
}
/**
 * Layer for organizing and blending multiple animation clips.
 * @interface AnimationLayer
 * @property {string} id - Unique identifier
 * @property {string} name - Layer name
 * @property {AnimationClip[]} clips - Animation clips in this layer
 * @property {number} weight - Layer influence (0-1) when blending
 * @property {string} blendMode - How to blend with other layers:
 *   - override: Replace lower layers
 *   - additive: Add to lower layers
 * @property {boolean} muted - Temporarily disable this layer
 * @property {boolean} solo - Only play this layer (mutes others)
 * @property {boolean} locked - Prevent editing of this layer
 */
export interface AnimationLayer {
    id: string;
    name: string;
    clips: AnimationClip[];
    weight: number;
    blendMode: 'override' | 'additive';
    muted: boolean;
    solo: boolean;
    locked: boolean;
}
/**
 * Main timeline controller for the animation system.
 * @interface AnimationTimeline
 * @property {string} id - Unique identifier
 * @property {string} name - Timeline name
 * @property {number} duration - Total timeline duration in seconds
 * @property {number} currentTime - Current playhead position in seconds
 * @property {number} playbackRate - Speed multiplier (1.0 = normal, 2.0 = double speed)
 * @property {AnimationLayer[]} layers - Stack of animation layers
 * @property {boolean} isPlaying - Whether timeline is currently playing
 * @property {boolean} isLooping - Whether to loop when reaching the end
 */
export interface AnimationTimeline {
    id: string;
    name: string;
    duration: number;
    currentTime: number;
    playbackRate: number;
    layers: AnimationLayer[];
    isPlaying: boolean;
    isLooping: boolean;
}
/**
 * Runtime state of the animation system.
 * @interface AnimationState
 * @property {AnimationTimeline} timeline - The main timeline
 * @property {Set<string>} activeClips - IDs of currently playing clips
 * @property {Map} activeActions - Map of active actions with their current state:
 *   - action: The AnimationAction instance
 *   - currentValue: Current interpolated value
 *   - weight: Current blend weight
 */
export interface AnimationState {
    timeline: AnimationTimeline;
    activeClips: Set<string>;
    activeActions: Map<string, {
        action: AnimationAction;
        currentValue: any;
        weight: number;
    }>;
}
/**
 * Event emitted by the animation system.
 * @interface AnimationEvent
 * @property {string} type - Event type:
 *   - start: Animation started
 *   - end: Animation completed
 *   - loop: Animation looped
 *   - marker: Marker reached
 *   - update: Frame update
 * @property {number} timestamp - When the event occurred
 * @property {any} [data] - Additional event data
 */
export interface AnimationEvent {
    type: 'start' | 'end' | 'loop' | 'marker' | 'update';
    timestamp: number;
    data?: any;
}