"""Timeline schema — source of truth for source material sequences."""

from dataclasses import dataclass, field
from datetime import datetime
from typing import Any, Dict, List, Optional
from uuid import UUID


@dataclass
class Timeline:
    """
    A user-created selection of source material.

    Exists before any job runs. Holds source references (chunk paths,
    asset IDs) and extraction config.

    Frame cache: extracted frames live at media/timelines/{id}/frames/
    as JPEGs. Any job on this timeline reads from the cache. Cache is
    rebuildable from chunks (clear + re-extract). For ephemeral sources
    (streams), the cache is the only record.

    Many jobs can work on the same timeline.
    """

    id: UUID
    name: str = ""
    source_asset_id: Optional[UUID] = None
    chunk_paths: List[str] = field(default_factory=list)
    profile_name: str = ""
    status: str = "created"  # created | cached | ready
    fps: float = 2.0
    frame_count: int = 0
    source_ephemeral: bool = False  # True for streams — cache can't be rebuilt

    created_at: Optional[datetime] = None