"""
core/grounding/target.py — Types partagés pour le grounding visuel

Dataclasses décrivant une cible à localiser (GroundingTarget) et
le résultat d'une localisation (GroundingResult).

Ces types sont la brique commune pour tous les modules de grounding :
template matching, OCR, VLM, CLIP, etc.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Dict, Optional


@dataclass
class GroundingTarget:
    """Description d'un élément UI à localiser sur l'écran.

    Attributs :
        text : texte visible de l'élément (bouton, label, etc.)
        description : description sémantique libre (ex: "le bouton Valider en bas à droite")
        template_b64 : capture visuelle de l'élément, encodée en base64 PNG/JPEG
        original_bbox : position d'origine lors de la capture {x, y, width, height}
    """
    text: str = ""
    description: str = ""
    template_b64: str = ""
    original_bbox: Optional[Dict[str, int]] = field(default=None)


@dataclass
class GroundingResult:
    """Résultat d'une localisation d'élément UI.

    Attributs :
        x : coordonnée X du centre de l'élément trouvé (pixels écran)
        y : coordonnée Y du centre de l'élément trouvé (pixels écran)
        method : méthode ayant produit le résultat ('template', 'ocr', 'vlm', 'clip', etc.)
        confidence : score de confiance [0.0 – 1.0]
        time_ms : temps de recherche en millisecondes
    """
    x: int
    y: int
    method: str
    confidence: float
    time_ms: float