"""Decode-layer ports and frame model."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Iterable, Iterator, Protocol

from yovision_brain.input import CancellationToken, InputPacket


class DecoderError(RuntimeError):
    """A safe and actionable decode failure."""


@dataclass(frozen=True, slots=True)
class DecodedFrame:
    sequence: int
    timestamp_ns: int
    logical_device_id: str
    profile_id: str
    width: int
    height: int
    pixel_format: str
    payload: bytes
    dimensions_changed: bool = False


class DecoderBackend(Protocol):
    media_formats: frozenset[str]

    def decode(
        self,
        packets: Iterable[InputPacket],
        cancellation: CancellationToken | None = None,
    ) -> Iterator[DecodedFrame]: ...