"""Common project-internal input types."""

from __future__ import annotations

from dataclasses import dataclass
from threading import Event
from typing import Iterator, Protocol


class InputError(RuntimeError):
    """A safe, actionable input adapter error."""


class CancellationToken:
    """Thread-safe cooperative cancellation without platform dependencies."""

    def __init__(self) -> None:
        self._event = Event()

    def cancel(self) -> None:
        self._event.set()

    @property
    def cancelled(self) -> bool:
        return self._event.is_set()


@dataclass(frozen=True, slots=True)
class InputPacket:
    sequence: int
    timestamp_ns: int | None
    logical_device_id: str
    profile_id: str
    width: int
    height: int
    media_format: str
    payload: bytes


class InputSource(Protocol):
    """Replaceable source boundary consumed by the future decode layer."""

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