/**
 * @file TimelineEditor.ts
 * @description Timeline System for Cutscenes, Cinematics, and Sequencing
 * PRO-1.4: Professional Editor Features
 *
 * Features:
 * - Multi-track timeline
 * - Track types: animation, audio, event, property, activation
 * - Keyframe animation with curves
 * - Clips with blending
 * - Markers and events
 * - Playback control
 * - Recording mode
 * - Debugger integration
 */
import type { EntityId, Vec2 } from '../core/types';
export type TimelinePlayState = 'stopped' | 'playing' | 'paused' | 'recording';
export type TimelineWrapMode = 'once' | 'loop' | 'pingPong' | 'clampForever';
export type TrackType = 'animation' | 'audio' | 'event' | 'property' | 'activation' | 'camera' | 'transform' | 'group' | 'override';
export type TangentMode = 'auto' | 'smooth' | 'linear' | 'constant' | 'free';
export type EasingFunction = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInQuint' | 'easeOutQuint' | 'easeInOutQuint' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInCirc' | 'easeOutCirc' | 'easeInOutCirc' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeInElastic' | 'easeOutElastic' | 'easeInOutElastic' | 'easeInBounce' | 'easeOutBounce' | 'easeInOutBounce';
export interface Keyframe<T = number> {
    id: string;
    time: number;
    value: T;
    /** Easing to next keyframe */
    easing?: EasingFunction;
    /** Bezier tangent mode */
    tangentMode?: TangentMode;
    /** In tangent (for bezier) */
    inTangent?: Vec2;
    /** Out tangent (for bezier) */
    outTangent?: Vec2;
    /** In weight (0-1) */
    inWeight?: number;
    /** Out weight (0-1) */
    outWeight?: number;
}
export interface AnimationCurve {
    id: string;
    property: string;
    keyframes: Keyframe<number>[];
    /** Pre-infinity mode */
    preWrap?: TimelineWrapMode;
    /** Post-infinity mode */
    postWrap?: TimelineWrapMode;
}
export interface BaseClip {
    id: string;
    name: string;
    trackId: string;
    /** Start time in timeline */
    startTime: number;
    /** Duration of clip */
    duration: number;
    /** Clip can be trimmed from start */
    clipIn?: number;
    /** Speed multiplier */
    speed?: number;
    /** Blend in duration */
    blendInDuration?: number;
    /** Blend out duration */
    blendOutDuration?: number;
    /** Custom color */
    color?: string;
    /** Is this clip muted? */
    muted?: boolean;
    /** Is this clip locked? */
    locked?: boolean;
}
export interface AnimationClip extends BaseClip {
    type: 'animation';
    /** Animation curves */
    curves: AnimationCurve[];
    /** Root motion */
    rootMotion?: {
        extractPosition: boolean;
        extractRotation: boolean;
    };
    /** Target binding */
    binding?: {
        type: 'entity' | 'component' | 'property';
        path: string;
    };
}
export interface AudioClip extends BaseClip {
    type: 'audio';
    /** Audio asset reference */
    audioSource: string;
    /** Volume (0-1) */
    volume: number;
    /** Volume curve */
    volumeCurve?: AnimationCurve;
    /** Spatial blend (0 = 2D, 1 = 3D) */
    spatialBlend?: number;
    /** Loop */
    loop?: boolean;
}
export interface EventClip extends BaseClip {
    type: 'event';
    /** Event name to fire */
    eventName: string;
    /** Event payload */
    payload?: Record<string, unknown>;
    /** Fire once or every frame */
    fireMode: 'once' | 'every-frame' | 'on-exit';
}
export interface PropertyClip extends BaseClip {
    type: 'property';
    /** Target property path */
    propertyPath: string;
    /** Property curves */
    curves: AnimationCurve[];
}
export interface ActivationClip extends BaseClip {
    type: 'activation';
    /** Entity to activate/deactivate */
    targetEntity: EntityId;
    /** Activation state */
    active: boolean;
}
export interface TransformClip extends BaseClip {
    type: 'transform';
    /** Position curve */
    positionCurve?: {
        x: AnimationCurve;
        y: AnimationCurve;
        z: AnimationCurve;
    };
    /** Rotation curve (euler) */
    rotationCurve?: {
        x: AnimationCurve;
        y: AnimationCurve;
        z: AnimationCurve;
    };
    /** Scale curve */
    scaleCurve?: {
        x: AnimationCurve;
        y: AnimationCurve;
        z: AnimationCurve;
    };
}
export interface CameraClip extends BaseClip {
    type: 'camera';
    /** Camera property curves */
    fieldOfView?: AnimationCurve;
    nearClip?: AnimationCurve;
    farClip?: AnimationCurve;
    /** Depth of field */
    dof?: {
        focusDistance: AnimationCurve;
        aperture: AnimationCurve;
        focalLength: AnimationCurve;
    };
    /** Camera shake */
    shake?: {
        amplitude: AnimationCurve;
        frequency: AnimationCurve;
    };
    /** Look-at target */
    lookAtTarget?: EntityId;
}
export type TimelineClip = AnimationClip | AudioClip | EventClip | PropertyClip | ActivationClip | TransformClip | CameraClip;
export interface BaseTrack {
    id: string;
    name: string;
    type: TrackType;
    /** Parent track (for grouping) */
    parentId?: string;
    /** Track color */
    color?: string;
    /** Is track muted? */
    muted?: boolean;
    /** Is track locked? */
    locked?: boolean;
    /** Is track collapsed in UI? */
    collapsed?: boolean;
    /** Track height in editor */
    height?: number;
    /** Clips on this track */
    clips: TimelineClip[];
    /** Override tracks (for track mixing) */
    overrides?: string[];
}
export interface AnimationTrack extends BaseTrack {
    type: 'animation';
    /** Binding target */
    binding?: {
        entityId: EntityId;
        animator?: string;
    };
    /** Default animator state */
    defaultState?: string;
}
export interface AudioTrack extends BaseTrack {
    type: 'audio';
    /** Output audio group */
    outputGroup?: string;
    /** Master volume */
    volume?: number;
}
export interface EventTrack extends BaseTrack {
    type: 'event';
    /** Target listener */
    listenerPath?: string;
}
export interface PropertyTrack extends BaseTrack {
    type: 'property';
    /** Target entity */
    targetEntity: EntityId;
    /** Property path */
    propertyPath: string;
}
export interface ActivationTrack extends BaseTrack {
    type: 'activation';
    /** Target entity */
    targetEntity: EntityId;
}
export interface TransformTrack extends BaseTrack {
    type: 'transform';
    /** Target entity */
    targetEntity: EntityId;
    /** Space */
    space: 'local' | 'world';
}
export interface CameraTrack extends BaseTrack {
    type: 'camera';
    /** Target camera entity */
    cameraEntity: EntityId;
}
export interface GroupTrack extends BaseTrack {
    type: 'group';
    /** Child track IDs */
    children: string[];
}
export type TimelineTrack = AnimationTrack | AudioTrack | EventTrack | PropertyTrack | ActivationTrack | TransformTrack | CameraTrack | GroupTrack;
export interface TimelineMarker {
    id: string;
    name: string;
    time: number;
    color?: string;
    /** Marker type */
    type: 'marker' | 'signal' | 'jump';
    /** For signal markers */
    signalName?: string;
    signalPayload?: Record<string, unknown>;
    /** For jump markers */
    jumpTarget?: string;
    jumpCondition?: string;
}
export interface TimelineDefinition {
    id: string;
    name: string;
    description?: string;
    /** Total duration */
    duration: number;
    /** Frames per second */
    fps: number;
    /** Wrap mode */
    wrapMode: TimelineWrapMode;
    /** Tracks */
    tracks: TimelineTrack[];
    /** Markers */
    markers: TimelineMarker[];
    /** Metadata */
    metadata?: {
        author?: string;
        version?: string;
        created?: number;
        modified?: number;
        tags?: string[];
    };
    /** Editor settings */
    editorSettings?: {
        snapToFrames: boolean;
        showCurves: boolean;
        showAudioWaveforms: boolean;
        zoom: number;
        scrollOffset: number;
    };
}
export type TimelineEventType = 'play' | 'pause' | 'stop' | 'seek' | 'marker' | 'signal' | 'clip-enter' | 'clip-exit' | 'loop' | 'complete' | 'event';
export interface TimelineEvent {
    type: TimelineEventType;
    time: number;
    data?: unknown;
}
export declare function applyEasing(t: number, easing?: EasingFunction): number;
export declare function evaluateCurve(curve: AnimationCurve, time: number): number;
export declare class TimelinePlayer {
    private definition;
    private state;
    private currentTime;
    private speed;
    private direction;
    /** Active clips per track */
    private activeClips;
    /** Previous time for detecting clip transitions */
    private previousTime;
    /** Event listeners */
    private listeners;
    /** Property bindings */
    private propertyBindings;
    /** Audio context */
    private audioContext?;
    private audioNodes;
    /** Debug mode */
    debugMode: boolean;
    private history;
    constructor(definition: TimelineDefinition);
    play(): void;
    pause(): void;
    stop(): void;
    seek(time: number): void;
    seekToMarker(markerName: string): boolean;
    setSpeed(speed: number): void;
    getSpeed(): number;
    update(dt: number): void;
    private processTracks;
    private processTrack;
    private onClipEnter;
    private onClipExit;
    private updateClip;
    private updateAnimationClip;
    private updatePropertyClip;
    private updateEventClip;
    private updateTransformClip;
    private updateCameraClip;
    private updateAudioClip;
    private fireEventClip;
    private playAudioClip;
    private stopAudioClip;
    private stopAllAudio;
    private processMarkers;
    private evaluateCondition;
    bindProperty(path: string, setter: (value: unknown) => void): void;
    unbindProperty(path: string): void;
    private applyProperty;
    on(event: TimelineEventType, listener: (event: TimelineEvent) => void): void;
    off(event: TimelineEventType, listener: (event: TimelineEvent) => void): void;
    private emit;
    getState(): TimelinePlayState;
    getCurrentTime(): number;
    getDuration(): number;
    getProgress(): number;
    isPlaying(): boolean;
    isPaused(): boolean;
    isStopped(): boolean;
    getDefinition(): TimelineDefinition;
    getHistory(): TimelineEvent[];
    clearHistory(): void;
    getDebugInfo(): {
        state: TimelinePlayState;
        time: number;
        duration: number;
        progress: number;
        speed: number;
        activeClipCount: number;
    };
}
export interface RecordingOptions {
    targetTrack: string;
    propertyPath?: string;
    sampleRate?: number;
    autoKeyMode?: 'none' | 'all' | 'modified';
}
export declare class TimelineRecorder {
    private player;
    private options;
    private recording;
    private recordedKeyframes;
    private lastSampleTime;
    constructor(player: TimelinePlayer, options: RecordingOptions);
    startRecording(): void;
    stopRecording(): Map<string, Keyframe<number>[]>;
    isRecording(): boolean;
    recordValue(property: string, value: number): void;
    getRecordedKeyframes(): Map<string, Keyframe<number>[]>;
}
export declare function createTimelineDefinition(name: string, duration?: number): TimelineDefinition;
export declare function createTimelinePlayer(definition: TimelineDefinition): TimelinePlayer;
export declare function createTimelineRecorder(player: TimelinePlayer, options: RecordingOptions): TimelineRecorder;
export declare function createTrack(name: string, type: TrackType): TimelineTrack;
export declare function createAnimationClip(trackId: string, startTime: number, duration: number): AnimationClip;
export declare function createAudioClip(trackId: string, startTime: number, duration: number, audioSource: string): AudioClip;
export declare function createEventClip(trackId: string, time: number, eventName: string): EventClip;
export declare function createPropertyClip(trackId: string, startTime: number, duration: number, propertyPath: string): PropertyClip;
export declare function createTransformClip(trackId: string, startTime: number, duration: number): TransformClip;
export declare function createCameraClip(trackId: string, startTime: number, duration: number): CameraClip;
export declare function createAnimationCurve(property: string): AnimationCurve;
export declare function createKeyframe<T = number>(time: number, value: T, easing?: EasingFunction): Keyframe<T>;
export declare function createMarker(name: string, time: number): TimelineMarker;
export declare function createSignalMarker(name: string, time: number, signalName: string, payload?: Record<string, unknown>): TimelineMarker;
