import type { ScreenRegion } from './ScreenRegion';

/**
 * Represents an image template used for visual element detection.
 * Templates are reference images that are matched against screen captures
 * to locate UI elements without relying on CSS selectors or DOM access.
 */
export interface ImageTemplate {
  /** Unique identifier for the template */
  id: string;
  /** Path to the template image file (relative to resources directory) */
  imagePath: string;
  /** Confidence threshold for matching (0.0-1.0, higher = more strict) */
  confidence: number;
  /** Optional region to limit search area for better performance */
  searchRegion?: ScreenRegion;
  /** Human-readable description of what this template represents */
  description: string;
}

/**
 * Template categories for organization and filtering.
 */
export type TemplateCategory = 
  | 'login'
  | 'navigation'
  | 'wizard'
  | 'button'
  | 'field'
  | 'modal'
  | 'indicator';

/**
 * Extended template with category metadata.
 */
export interface CategorizedTemplate extends ImageTemplate {
  category: TemplateCategory;
  stepId?: number;
}

/**
 * Create an ImageTemplate with default confidence.
 */
export function createImageTemplate(
  id: string,
  imagePath: string,
  description: string,
  options?: {
    confidence?: number;
    searchRegion?: ScreenRegion;
  }
): ImageTemplate {
  return {
    id,
    imagePath,
    description,
    confidence: options?.confidence ?? 0.9,
    searchRegion: options?.searchRegion,
  };
}

/**
 * Validate that an ImageTemplate has all required fields.
 */
export function isValidTemplate(template: unknown): template is ImageTemplate {
  if (typeof template !== 'object' || template === null) {
    return false;
  }
  
  const t = template as Record<string, unknown>;
  
  return (
    typeof t.id === 'string' &&
    t.id.length > 0 &&
    typeof t.imagePath === 'string' &&
    t.imagePath.length > 0 &&
    typeof t.confidence === 'number' &&
    t.confidence >= 0 &&
    t.confidence <= 1 &&
    typeof t.description === 'string'
  );
}

/**
 * Default confidence thresholds for different template types.
 */
export const DEFAULT_CONFIDENCE = {
  /** High confidence for exact matches (buttons, icons) */
  HIGH: 0.95,
  /** Standard confidence for most UI elements */
  STANDARD: 0.9,
  /** Lower confidence for variable elements (text fields with content) */
  LOW: 0.8,
  /** Minimum acceptable confidence */
  MINIMUM: 0.7,
  /** Very low confidence for testing/debugging template matching issues */
  DEBUG: 0.5,
} as const;