"""Cross-platform full-screen capture via `mss` (Windows, macOS, Linux/X11)."""
from __future__ import annotations

import time
from pathlib import Path
from typing import Optional

from config import SCREENSHOT_DIR


class CaptureError(RuntimeError):
    pass


def capture(prefix: str = "shot") -> str:
    """Grab the primary monitor to a PNG and return its path."""
    try:
        import mss
        import mss.tools
    except Exception as e:  # pragma: no cover
        raise CaptureError(f"mss not available: {e}")

    ts = int(time.time() * 1000)
    path = SCREENSHOT_DIR / f"{prefix}_{ts}.png"
    try:
        with mss.mss() as sct:
            monitor = sct.monitors[1]  # [0] is the virtual "all monitors" rect
            img = sct.grab(monitor)
            mss.tools.to_png(img.rgb, img.size, output=str(path))
    except Exception as e:
        raise CaptureError(
            f"Screen capture failed ({e}). On macOS grant Screen Recording; "
            f"on Linux use an X11 session (Wayland needs the screenshot portal)."
        )
    return str(path)