from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class Driver(ABC):
    """Driver-independent device capability interface.

    Implementations may hold a live connection handle, but no task or business
    state belongs here.
    """

    @abstractmethod
    def connect(self) -> None:
        """Open the device connection."""

    @abstractmethod
    def disconnect(self) -> None:
        """Close the device connection."""

    @abstractmethod
    def screenshot(self) -> bytes:
        """Return the current screen as image bytes."""

    @abstractmethod
    def tap(self, x: float, y: float) -> None:
        """Tap the screen at the given coordinates."""

    @abstractmethod
    def long_press(self, x: float, y: float, duration_ms: int = 1200) -> None:
        """Press and hold at the given coordinates for ``duration_ms``.

        Some platforms ignore ``duration_ms`` (fixed system hold duration).
        """

    @abstractmethod
    def swipe(
        self,
        start_x: float,
        start_y: float,
        end_x: float,
        end_y: float,
        duration_ms: int = 500,
    ) -> None:
        """Swipe between two screen coordinates."""

    @abstractmethod
    def swipe_path(
        self, waypoints: list[tuple[float, float]], duration_ms: int
    ) -> None:
        """Swipe through a sequence of waypoints in one continuous touch."""

    @abstractmethod
    def double_tap(self, x: float, y: float, interval_ms: int = 80) -> None:
        """Tap twice at the given coordinates with ``interval_ms`` between."""

    @abstractmethod
    def input(self, text: str) -> None:
        """Input text into the current focused field."""

    @abstractmethod
    def launch(self, app_id: str) -> None:
        """Launch an app by bundle id or driver-supported app identifier."""

    @abstractmethod
    def terminate(self, app_id: str) -> None:
        """Terminate an app by bundle id or driver-supported app identifier."""

    @abstractmethod
    def tree(self) -> Any:
        """Return the raw UI tree from the device driver."""

    @abstractmethod
    def home(self) -> None:
        """Press the device home button."""

    @abstractmethod
    def lock(self) -> None:
        """Lock the device."""

    @abstractmethod
    def unlock(self) -> None:
        """Unlock the device."""