gridpilot.gg/packages/application/ports/IScreenAutomation.ts

import { StepId } from '../../domain/value-objects/StepId';
import type { ImageTemplate } from '../../domain/value-objects/ImageTemplate';
import type { ElementLocation, LoginDetectionResult, ScreenRegion } from '../../domain/value-objects/ScreenRegion';
import {
  NavigationResult,
  FormFillResult,
  ClickResult,
  WaitResult,
  ModalResult,
  AutomationResult,
} from './AutomationResults';

/**
 * Screen capture result containing the captured image data.
 */
export interface ScreenCaptureResult {
  success: boolean;
  data?: Buffer;
  width?: number;
  height?: number;
  error?: string;
}

/**
 * Window information for browser window management.
 */
export interface WindowInfo {
  title: string;
  bounds: ScreenRegion;
  handle: number;
  isActive: boolean;
}

/**
 * Result of window focus operation.
 */
export interface WindowFocusResult {
  success: boolean;
  window?: WindowInfo;
  error?: string;
}

/**
 * Extended browser automation interface for OS-level screen automation.
 * 
 * This interface extends the base IBrowserAutomation with screen recognition
 * capabilities for TOS-compliant automation that doesn't use browser DevTools.
 * 
 * Key differences from browser-based automation:
 * - Uses image template matching instead of CSS selectors
 * - Works with screen coordinates instead of DOM elements
 * - Requires explicit window focus management
 * - No direct access to page content or JavaScript execution
 */
export interface IScreenAutomation {
  // ============================================
  // LEGACY BROWSER AUTOMATION METHODS
  // (Maintained for backward compatibility)
  // ============================================
  
  /**
   * Navigate to a URL using keyboard shortcuts (Cmd/Ctrl+L, type URL, Enter).
   * Requires browser window to be focused.
   */
  navigateToPage(url: string): Promise<NavigationResult>;
  
  /**
   * Fill a form field by selecting all text and typing new value.
   * Requires the field to already be focused.
   */
  fillFormField(fieldName: string, value: string): Promise<FormFillResult>;
  
  /**
   * Click at a screen position (accepts coordinates or template ID).
   */
  clickElement(target: string): Promise<ClickResult>;
  
  /**
   * Wait for a condition (time-based in screen automation mode).
   */
  waitForElement(target: string, maxWaitMs?: number): Promise<WaitResult>;
  
  /**
   * Handle modal dialogs using keyboard (Enter/Escape).
   */
  handleModal(stepId: StepId, action: string): Promise<ModalResult>;
  
  /**
   * Execute a complete workflow step.
   */
  executeStep?(stepId: StepId, config: Record<string, unknown>): Promise<AutomationResult>;
  
  /**
   * Initialize the automation connection.
   */
  connect?(): Promise<void>;
  
  /**
   * Clean up resources.
   */
  disconnect?(): Promise<void>;
  
  /**
   * Check if automation is ready.
   */
  isConnected?(): boolean;

  // ============================================
  // SCREEN AUTOMATION METHODS
  // (New methods for OS-level automation)
  // ============================================
  
  /**
   * Detect login state by searching for known UI indicators on screen.
   * Uses template matching to find login-related elements.
   * 
   * @returns LoginDetectionResult with confidence and detected indicators
   */
  detectLoginState?(): Promise<LoginDetectionResult>;
  
  /**
   * Find a UI element on screen using image template matching.
   * 
   * @param template - The image template to search for
   * @returns ElementLocation if found, null if not found
   */
  findElement?(template: ImageTemplate): Promise<ElementLocation | null>;
  
  /**
   * Bring the browser window to the foreground.
   * Searches for windows matching a title pattern (e.g., "iRacing").
   * 
   * @param titlePattern - Optional window title pattern to match
   * @returns WindowFocusResult indicating success/failure
   */
  focusBrowserWindow?(titlePattern?: string): Promise<WindowFocusResult>;
  
  /**
   * Capture a region of the screen.
   * 
   * @param region - Optional region to capture (full screen if omitted)
   * @returns ScreenCaptureResult with image data
   */
  captureScreen?(region?: ScreenRegion): Promise<ScreenCaptureResult>;
  
  /**
   * Click on a found element location.
   * 
   * @param location - The element location from findElement
   * @returns ClickResult indicating success/failure
   */
  clickAtLocation?(location: ElementLocation): Promise<ClickResult>;
  
  /**
   * Wait for a template to appear on screen.
   * 
   * @param template - The image template to wait for
   * @param maxWaitMs - Maximum time to wait in milliseconds
   * @returns WaitResult with timing information
   */
  waitForTemplate?(template: ImageTemplate, maxWaitMs?: number): Promise<WaitResult>;
}

/**
 * Type alias for backward compatibility.
 * IBrowserAutomation is now a subset of IScreenAutomation.
 */
export type IBrowserAutomation = Pick<
  IScreenAutomation,
  | 'navigateToPage'
  | 'fillFormField'
  | 'clickElement'
  | 'waitForElement'
  | 'handleModal'
  | 'executeStep'
  | 'connect'
  | 'disconnect'
  | 'isConnected'
>;