"""Driver protocol: dump one step's UI tree for a surface."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Optional, Protocol


@dataclass
class DumpResult:
    surface: str
    driver: str
    window: dict[str, Any]
    tree: dict[str, Any]
    index: list[dict[str, Any]]
    locatable: list[dict[str, Any]]
    stats: dict[str, Any]
    selection: dict[str, Any] = field(default_factory=dict)
    url: str = ""
    page_title: str = ""
    locatable_text: str = ""
    tree_text: str = ""
    screenshot_bytes: Optional[bytes] = None  # if set, artifacts write screen.png from bytes
    use_hwnd_screenshot: bool = True  # windows: ImageGrab by hwnd


class SurfaceDriver(Protocol):
    def dump(
        self,
        *,
        info: Any,
        selection_meta: dict[str, Any],
        max_depth: int = 16,
        max_nodes: int = 8000,
        warmup_mode: str = "full",
        merge_same_pid_if_sparse: bool = True,
        warmed_pids: Optional[set[int]] = None,
    ) -> DumpResult: ...