@epsilon-asi/actors 0.0.22 → 0.0.33

package/src/native/drivers.ts

@@ -0,0 +1,38 @@
+import type { NativeMouseButton, NativePoint, NativeRegion, NativeSize, NativeWindowInfo } from './types.js';
+
+export interface NativeMouseDriver {
+  getPosition(): Promise<NativePoint>;
+  move(point: NativePoint): Promise<void>;
+  click(button: NativeMouseButton): Promise<void>;
+}
+
+export interface NativeKeyboardDriver {
+  type(text: string, options?: { delayMs?: number }): Promise<void>;
+  pressKey(key: string): Promise<void>;
+  pressShortcut(keys: readonly string[]): Promise<void>;
+}
+
+export interface NativeScreenDriver {
+  width(): Promise<number>;
+  height(): Promise<number>;
+}
+
+export interface NativeWindowHandle {
+  info(): Promise<NativeWindowInfo>;
+  focus(): Promise<void>;
+  minimize(): Promise<void>;
+  restore(): Promise<void>;
+  move(point: NativePoint): Promise<void>;
+  resize(size: NativeSize): Promise<void>;
+  setFullscreen?(fullscreen: boolean): Promise<void>;
+  toggleFullscreen?(): Promise<void>;
+}
+
+export interface NativeWindowDriver {
+  list(): Promise<NativeWindowHandle[]>;
+  active?(): Promise<NativeWindowHandle | null>;
+}
+
+export interface AppleScriptExecutor {
+  execute(script: string, options?: { timeoutMs?: number }): Promise<string>;
+}

package/src/native/errors.ts

@@ -0,0 +1,51 @@
+export class NativeAutomationError extends Error {
+  constructor(message: string, readonly meta: Record<string, unknown> = {}) {
+    super(message);
+    this.name = 'NativeAutomationError';
+  }
+}
+
+export class UnsupportedPlatformError extends NativeAutomationError {
+  constructor(platform: NodeJS.Platform) {
+    super(`Native automation is not supported on platform: ${platform}.`, { platform });
+    this.name = 'UnsupportedPlatformError';
+  }
+}
+
+export class NativeDependencyError extends NativeAutomationError {
+  constructor(packageName: string, cause?: unknown) {
+    super(
+      `Native automation dependency ${packageName} is not available. Install the optional native automation peer dependencies before using this feature.`,
+      cause === undefined ? { packageName } : { packageName, cause }
+    );
+    this.name = 'NativeDependencyError';
+  }
+}
+
+export class NativeWindowNotFoundError extends NativeAutomationError {
+  constructor(meta: Record<string, unknown>) {
+    super('Native window was not found.', meta);
+    this.name = 'NativeWindowNotFoundError';
+  }
+}
+
+export class NativeImageNotFoundError extends NativeAutomationError {
+  constructor(meta: Record<string, unknown>) {
+    super('Native image/template was not found on screen.', meta);
+    this.name = 'NativeImageNotFoundError';
+  }
+}
+
+export class NativeFileDialogError extends NativeAutomationError {
+  constructor(message: string, meta: Record<string, unknown> = {}) {
+    super(message, meta);
+    this.name = 'NativeFileDialogError';
+  }
+}
+
+export class CoordinateCalibrationError extends NativeAutomationError {
+  constructor(message: string, meta: Record<string, unknown> = {}) {
+    super(message, meta);
+    this.name = 'CoordinateCalibrationError';
+  }
+}

package/src/native/index.ts

@@ -0,0 +1,12 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './drivers.js';
+export * from './NativeActionRegistry.js';
+export * from './NativeAutomation.js';
+export * from './NativeCoordinateMapper.js';
+export * from './NativeFileDialogService.js';
+export * from './NativeImageFinder.js';
+export * from './NativeKeyboard.js';
+export * from './NativeMouse.js';
+export * from './NativeWindowService.js';
+export * from './WindowMatcher.js';

package/src/native/macos/MacOSAccessibilityWindowDriver.ts

@@ -0,0 +1,183 @@
+import type { Logger } from '../../logging/Logger.js';
+import type { NativeWindowDriver, NativeWindowHandle } from '../drivers.js';
+import type { NativePoint, NativeRegion, NativeSize, NativeWindowInfo } from '../types.js';
+import { appleScriptString } from '../utils/appleScriptEscape.js';
+import { MacOSAppleScriptClient } from './MacOSAppleScriptClient.js';
+
+const FIELD_SEPARATOR = '\u001f';
+const ROW_SEPARATOR = '\u001e';
+
+function parseBoolean(value: string): boolean | undefined {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return undefined;
+}
+
+function parseNumber(value: string): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+class MacOSAccessibilityWindowHandle implements NativeWindowHandle {
+  constructor(private readonly client: MacOSAppleScriptClient, private currentInfo: NativeWindowInfo) {}
+
+  async info(): Promise<NativeWindowInfo> {
+    return this.currentInfo;
+  }
+
+  async focus(): Promise<void> {
+    await this.client.focusWindow(this.matcher(), this.currentInfo.appName ?? 'Google Chrome');
+    this.currentInfo = { ...this.currentInfo, isFocused: true };
+  }
+
+  async minimize(): Promise<void> {
+    await this.client.minimize(this.matcher(), this.currentInfo.appName ?? 'Google Chrome');
+    this.currentInfo = { ...this.currentInfo, isMinimized: true };
+  }
+
+  async restore(): Promise<void> {
+    await this.executeOnWindow(`set value of attribute "AXMinimized" of candidateWindow to false`);
+    this.currentInfo = { ...this.currentInfo, isMinimized: false };
+  }
+
+  async move(point: NativePoint): Promise<void> {
+    await this.executeOnWindow(`set position of candidateWindow to {${Math.round(point.x)}, ${Math.round(point.y)}}`);
+    this.currentInfo = {
+      ...this.currentInfo,
+      region: { ...this.currentInfo.region, x: Math.round(point.x), y: Math.round(point.y) }
+    };
+  }
+
+  async resize(size: NativeSize): Promise<void> {
+    await this.executeOnWindow(`set size of candidateWindow to {${Math.round(size.width)}, ${Math.round(size.height)}}`);
+    this.currentInfo = {
+      ...this.currentInfo,
+      region: { ...this.currentInfo.region, width: Math.round(size.width), height: Math.round(size.height) }
+    };
+  }
+
+  async setFullscreen(fullscreen: boolean): Promise<void> {
+    await this.client.setFullscreen(this.matcher(), fullscreen, this.currentInfo.appName ?? 'Google Chrome');
+    this.currentInfo = { ...this.currentInfo, isFullscreen: fullscreen };
+  }
+
+  async toggleFullscreen(): Promise<void> {
+    await this.client.toggleFullscreen(this.matcher(), this.currentInfo.appName ?? 'Google Chrome');
+    if (this.currentInfo.isFullscreen === undefined) {
+      this.currentInfo = { ...this.currentInfo };
+    } else {
+      this.currentInfo = { ...this.currentInfo, isFullscreen: !this.currentInfo.isFullscreen };
+    }
+  }
+
+  private matcher() {
+    const matcher: { appName?: string; title?: string } = {};
+    if (this.currentInfo.appName !== undefined) matcher.appName = this.currentInfo.appName;
+    matcher.title = this.currentInfo.title;
+    return matcher;
+  }
+
+  private async executeOnWindow(action: string): Promise<void> {
+    const appName = this.currentInfo.appName ?? 'Google Chrome';
+    const title = this.currentInfo.title;
+    const script = `
+      tell application "System Events"
+        tell process ${appleScriptString(appName)}
+          repeat with candidateWindow in windows
+            if name of candidateWindow is ${appleScriptString(title)} then
+              ${action}
+              return
+            end if
+          end repeat
+        end tell
+      end tell
+    `;
+    await this.client.execute(script);
+  }
+}
+
+export class MacOSAccessibilityWindowDriver implements NativeWindowDriver {
+  constructor(private readonly client: MacOSAppleScriptClient, private readonly logger?: Logger) {}
+
+  async list(): Promise<NativeWindowHandle[]> {
+    const script = `
+      set fieldSeparator to ASCII character 31
+      set rowSeparator to ASCII character 30
+      set rows to {}
+      tell application "System Events"
+        repeat with appProcess in application processes
+          set appName to name of appProcess
+          repeat with candidateWindow in windows of appProcess
+            set windowTitle to ""
+            set px to 0
+            set py to 0
+            set windowWidth to 0
+            set windowHeight to 0
+            set minimizedValue to ""
+            set fullscreenValue to ""
+            try
+              set windowTitle to name of candidateWindow
+            end try
+            try
+              set windowPosition to position of candidateWindow
+              set px to item 1 of windowPosition
+              set py to item 2 of windowPosition
+            end try
+            try
+              set windowSize to size of candidateWindow
+              set windowWidth to item 1 of windowSize
+              set windowHeight to item 2 of windowSize
+            end try
+            try
+              set minimizedValue to (value of attribute "AXMinimized" of candidateWindow) as text
+            end try
+            try
+              set fullscreenValue to (value of attribute "AXFullScreen" of candidateWindow) as text
+            end try
+            copy (appName & fieldSeparator & windowTitle & fieldSeparator & px & fieldSeparator & py & fieldSeparator & windowWidth & fieldSeparator & windowHeight & fieldSeparator & minimizedValue & fieldSeparator & fullscreenValue) to end of rows
+          end repeat
+        end repeat
+      end tell
+      set AppleScript's text item delimiters to rowSeparator
+      return rows as text
+    `;
+
+    try {
+      const output = await this.client.execute(script);
+      if (output.length === 0) return [];
+      return output.split(ROW_SEPARATOR)
+        .map(row => this.parseRow(row))
+        .filter((info): info is NativeWindowInfo => info !== null)
+        .map(info => new MacOSAccessibilityWindowHandle(this.client, info));
+    } catch (error) {
+      this.logger?.debug('Failed to list windows through macOS Accessibility.', { error });
+      throw error;
+    }
+  }
+
+  private parseRow(row: string): NativeWindowInfo | null {
+    const fields = row.split(FIELD_SEPARATOR);
+    if (fields.length < 8) return null;
+    const [appName, title, xRaw, yRaw, widthRaw, heightRaw, minimizedRaw, fullscreenRaw] = fields;
+    if (appName === undefined || title === undefined || xRaw === undefined || yRaw === undefined || widthRaw === undefined || heightRaw === undefined) {
+      return null;
+    }
+
+    const region: NativeRegion = {
+      x: parseNumber(xRaw),
+      y: parseNumber(yRaw),
+      width: parseNumber(widthRaw),
+      height: parseNumber(heightRaw)
+    };
+    const info: NativeWindowInfo = {
+      appName,
+      title,
+      region
+    };
+    const isMinimized = parseBoolean(minimizedRaw ?? '');
+    const isFullscreen = parseBoolean(fullscreenRaw ?? '');
+    if (isMinimized !== undefined) info.isMinimized = isMinimized;
+    if (isFullscreen !== undefined) info.isFullscreen = isFullscreen;
+    return info;
+  }
+}

package/src/native/macos/MacOSAppleScriptClient.ts

@@ -0,0 +1,182 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AppleScriptExecutor } from '../drivers.js';
+import type { WindowMatcher } from '../types.js';
+import { appleScriptString } from '../utils/appleScriptEscape.js';
+
+const execFileAsync = promisify(execFile);
+
+export class OsaScriptExecutor implements AppleScriptExecutor {
+  async execute(script: string, options: { timeoutMs?: number } = {}): Promise<string> {
+    const { stdout } = await execFileAsync('osascript', ['-l', 'AppleScript', '-e', script], {
+      timeout: options.timeoutMs ?? 15_000,
+      maxBuffer: 1024 * 1024
+    });
+    return stdout.trim();
+  }
+}
+
+export interface MacOSAppleScriptClientOptions {
+  executor?: AppleScriptExecutor;
+  timeoutMs?: number;
+}
+
+function matcherCondition(matcher: WindowMatcher): string {
+  const conditions: string[] = [];
+  if (matcher.title !== undefined) {
+    conditions.push(`name of candidateWindow is ${appleScriptString(matcher.title)}`);
+  }
+  if (matcher.titleIncludes !== undefined) {
+    conditions.push(`name of candidateWindow contains ${appleScriptString(matcher.titleIncludes)}`);
+  }
+  if (matcher.role !== undefined) {
+    conditions.push(`role of candidateWindow is ${appleScriptString(matcher.role)}`);
+  }
+  return conditions.length === 0 ? 'true' : conditions.join(' and ');
+}
+
+function processTarget(matcher: WindowMatcher, fallbackAppName: string): string {
+  return appleScriptString(matcher.appName ?? fallbackAppName);
+}
+
+export class MacOSAppleScriptClient {
+  private readonly executor: AppleScriptExecutor;
+  private readonly timeoutMs: number;
+
+  constructor(options: MacOSAppleScriptClientOptions = {}) {
+    this.executor = options.executor ?? new OsaScriptExecutor();
+    this.timeoutMs = options.timeoutMs ?? 15_000;
+  }
+
+  async execute(script: string, timeoutMs?: number): Promise<string> {
+    return this.executor.execute(script, { timeoutMs: timeoutMs ?? this.timeoutMs });
+  }
+
+  async isWindowOpen(matcher: WindowMatcher, fallbackAppName = 'Google Chrome'): Promise<boolean> {
+    const script = `
+      tell application "System Events"
+        if not (exists process ${processTarget(matcher, fallbackAppName)}) then return "false"
+        tell process ${processTarget(matcher, fallbackAppName)}
+          repeat with candidateWindow in windows
+            if ${matcherCondition(matcher)} then return "true"
+          end repeat
+        end tell
+      end tell
+      return "false"
+    `;
+    return (await this.execute(script)) === 'true';
+  }
+
+  async focusWindow(matcher: WindowMatcher, fallbackAppName = 'Google Chrome'): Promise<void> {
+    const script = `
+      tell application ${processTarget(matcher, fallbackAppName)} to activate
+      tell application "System Events"
+        tell process ${processTarget(matcher, fallbackAppName)}
+          repeat with candidateWindow in windows
+            if ${matcherCondition(matcher)} then
+              perform action "AXRaise" of candidateWindow
+              return
+            end if
+          end repeat
+        end tell
+      end tell
+    `;
+    await this.execute(script);
+  }
+
+  async setFullscreen(matcher: WindowMatcher, fullscreen: boolean, fallbackAppName = 'Google Chrome'): Promise<void> {
+    const desired = fullscreen ? 'true' : 'false';
+    const script = `
+      tell application ${processTarget(matcher, fallbackAppName)} to activate
+      tell application "System Events"
+        tell process ${processTarget(matcher, fallbackAppName)}
+          repeat with candidateWindow in windows
+            if ${matcherCondition(matcher)} then
+              set currentFullscreen to false
+              try
+                set currentFullscreen to value of attribute "AXFullScreen" of candidateWindow
+              end try
+              if currentFullscreen is not ${desired} then
+                try
+                  perform action "AXPress" of (first button of candidateWindow whose subrole is "AXFullScreenButton")
+                on error
+                  click (first button of candidateWindow whose subrole is "AXFullScreenButton")
+                end try
+              end if
+              return
+            end if
+          end repeat
+        end tell
+      end tell
+    `;
+    await this.execute(script);
+  }
+
+  async toggleFullscreen(matcher: WindowMatcher, fallbackAppName = 'Google Chrome'): Promise<void> {
+    const script = `
+      tell application ${processTarget(matcher, fallbackAppName)} to activate
+      tell application "System Events"
+        tell process ${processTarget(matcher, fallbackAppName)}
+          repeat with candidateWindow in windows
+            if ${matcherCondition(matcher)} then
+              try
+                perform action "AXPress" of (first button of candidateWindow whose subrole is "AXFullScreenButton")
+              on error
+                click (first button of candidateWindow whose subrole is "AXFullScreenButton")
+              end try
+              return
+            end if
+          end repeat
+        end tell
+      end tell
+    `;
+    await this.execute(script);
+  }
+
+  async minimize(matcher: WindowMatcher, fallbackAppName = 'Google Chrome'): Promise<void> {
+    const script = `
+      tell application "System Events"
+        tell process ${processTarget(matcher, fallbackAppName)}
+          repeat with candidateWindow in windows
+            if ${matcherCondition(matcher)} then
+              try
+                perform action "AXPress" of (first button of candidateWindow whose subrole is "AXMinimizeButton")
+              on error
+                set value of attribute "AXMinimized" of candidateWindow to true
+              end try
+              return
+            end if
+          end repeat
+        end tell
+      end tell
+    `;
+    await this.execute(script);
+  }
+
+  async selectFileInOpenDialog(filePath: string, appName = 'Google Chrome', timeoutMs?: number): Promise<void> {
+    const script = `
+      set targetPath to ${appleScriptString(filePath)}
+      tell application ${appleScriptString(appName)} to activate
+      tell application "System Events"
+        tell process ${appleScriptString(appName)}
+          set frontmost to true
+          set waited to 0
+          repeat while waited < 100
+            if (exists window 1) then exit repeat
+            delay 0.1
+            set waited to waited + 1
+          end repeat
+          keystroke "g" using {command down, shift down}
+          delay 0.2
+          set the clipboard to targetPath
+          keystroke "v" using {command down}
+          delay 0.1
+          key code 36
+          delay 0.2
+          key code 36
+        end tell
+      end tell
+    `;
+    await this.execute(script, timeoutMs);
+  }
+}

package/src/native/macos/MacOSFileDialogAccessibilityStrategy.ts

@@ -0,0 +1,11 @@
+import type { SelectFileOptions } from '../types.js';
+import type { FileDialogAccessibilityStrategy } from '../NativeFileDialogService.js';
+import { MacOSAppleScriptClient } from './MacOSAppleScriptClient.js';
+
+export class MacOSFileDialogAccessibilityStrategy implements FileDialogAccessibilityStrategy {
+  constructor(private readonly client: MacOSAppleScriptClient, private readonly defaultAppName = 'Google Chrome') {}
+
+  async selectFile(filePath: string, options: SelectFileOptions): Promise<void> {
+    await this.client.selectFileInOpenDialog(filePath, options.appName ?? this.defaultAppName, options.timeoutMs);
+  }
+}

package/src/native/macos/MacOSNativeAutomation.ts

@@ -0,0 +1,86 @@
+import type { NativeAutomation, NativeAutomationFactoryArgs } from '../types.js';
+import { DefaultNativeActionRegistry, registerDefaultNativeActions } from '../NativeActionRegistry.js';
+import { HumanizedNativeMouse, type HumanizedNativeMouseOptions } from '../NativeMouse.js';
+import { DefaultNativeKeyboard } from '../NativeKeyboard.js';
+import { DefaultNativeWindowService, type NativeWindowServiceDependencies } from '../NativeWindowService.js';
+import { DefaultNativeImageFinder } from '../NativeImageFinder.js';
+import { ImageBasedCoordinateMapper, type ImageBasedCoordinateMapperOptions } from '../NativeCoordinateMapper.js';
+import { DefaultNativeFileDialogService, type NativeFileDialogServiceDependencies } from '../NativeFileDialogService.js';
+import { NutNativeMouseDriver } from '../nut/NutNativeMouseDriver.js';
+import { NutNativeKeyboardDriver } from '../nut/NutNativeKeyboardDriver.js';
+import { NutNativeScreenDriver } from '../nut/NutNativeScreenDriver.js';
+import { NutNativeWindowDriver } from '../nut/NutNativeWindowDriver.js';
+import { FallbackNativeWindowDriver } from '../CompositeNativeWindowDriver.js';
+import { MacOSAccessibilityWindowDriver } from './MacOSAccessibilityWindowDriver.js';
+import { NutNativeImageFinderDriver, type NutNativeImageFinderOptions } from '../nut/NutNativeImageFinder.js';
+import { MacOSAppleScriptClient, type MacOSAppleScriptClientOptions } from './MacOSAppleScriptClient.js';
+import { MacOSFileDialogAccessibilityStrategy } from './MacOSFileDialogAccessibilityStrategy.js';
+
+export function createMacOSNativeAutomation(args: NativeAutomationFactoryArgs): NativeAutomation {
+  const nativeConfig = args.config.native;
+  const mouseDriver = new NutNativeMouseDriver();
+  const keyboardDriver = new NutNativeKeyboardDriver();
+  const screenDriver = new NutNativeScreenDriver();
+  const appleScriptOptions: MacOSAppleScriptClientOptions = {};
+  const osascriptTimeoutMs = nativeConfig?.macos?.osascriptTimeoutMs ?? args.config.defaultTimeoutMs;
+  if (osascriptTimeoutMs !== undefined) appleScriptOptions.timeoutMs = osascriptTimeoutMs;
+  const appleScriptClient = new MacOSAppleScriptClient(appleScriptOptions);
+  const windowDriver = new FallbackNativeWindowDriver(
+    new MacOSAccessibilityWindowDriver(appleScriptClient, args.logger),
+    new NutNativeWindowDriver(),
+    args.logger
+  );
+  const keyboard = new DefaultNativeKeyboard(keyboardDriver);
+  const imageDriverOptions: NutNativeImageFinderOptions = { enableNlMatcher: true };
+  if (nativeConfig?.templatesDir !== undefined) imageDriverOptions.templatesDir = nativeConfig.templatesDir;
+  if (nativeConfig?.imageConfidence !== undefined) imageDriverOptions.confidence = nativeConfig.imageConfidence;
+  const imageDriver = new NutNativeImageFinderDriver(imageDriverOptions);
+  const images = new DefaultNativeImageFinder(imageDriver, args.config.defaultTimeoutMs);
+  const coordinateOptions: ImageBasedCoordinateMapperOptions = {
+    images,
+    logger: args.logger
+  };
+  const coordinateTimeoutMs = nativeConfig?.coordinateCalibration?.timeoutMs ?? args.config.defaultTimeoutMs;
+  if (coordinateTimeoutMs !== undefined) coordinateOptions.defaultTimeoutMs = coordinateTimeoutMs;
+  if (nativeConfig?.coordinateCalibration?.cacheTtlMs !== undefined) {
+    coordinateOptions.defaultCacheTtlMs = nativeConfig.coordinateCalibration.cacheTtlMs;
+  }
+  const coordinates = new ImageBasedCoordinateMapper(coordinateOptions);
+  const mouseOptions: HumanizedNativeMouseOptions = { coordinateMapper: coordinates };
+  if (nativeConfig?.mouse?.jitterPixels !== undefined) mouseOptions.jitterPixels = nativeConfig.mouse.jitterPixels;
+  if (nativeConfig?.mouse?.minJitterPixels !== undefined) mouseOptions.minJitterPixels = nativeConfig.mouse.minJitterPixels;
+  if (nativeConfig?.mouse?.moveSpeed !== undefined) mouseOptions.moveSpeed = nativeConfig.mouse.moveSpeed;
+  const mouse = new HumanizedNativeMouse(mouseDriver, mouseOptions);
+  const windowOptions: NativeWindowServiceDependencies = {
+    driver: windowDriver,
+    screen: screenDriver,
+    mouse,
+    images,
+    logger: args.logger
+  };
+  if (args.config.defaultTimeoutMs !== undefined) windowOptions.defaultTimeoutMs = args.config.defaultTimeoutMs;
+  const windows = new DefaultNativeWindowService(windowOptions);
+  const fileDialogOptions: NativeFileDialogServiceDependencies = {
+    keyboard,
+    mouse,
+    images,
+    accessibility: new MacOSFileDialogAccessibilityStrategy(appleScriptClient, nativeConfig?.macos?.targetApplicationName ?? 'Google Chrome'),
+    logger: args.logger
+  };
+  if (args.config.defaultTimeoutMs !== undefined) fileDialogOptions.defaultTimeoutMs = args.config.defaultTimeoutMs;
+  const fileDialogs = new DefaultNativeFileDialogService(fileDialogOptions);
+
+  const automation = {
+    windows,
+    fileDialogs,
+    mouse,
+    keyboard,
+    coordinates,
+    images,
+    actions: undefined as unknown as DefaultNativeActionRegistry
+  } satisfies Omit<NativeAutomation, 'actions'> & { actions: DefaultNativeActionRegistry };
+
+  const registry = new DefaultNativeActionRegistry(() => ({ automation, logger: args.logger }));
+  automation.actions = registerDefaultNativeActions(registry, automation, args.logger);
+  return automation;
+}

package/src/native/nut/NutNativeImageFinder.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { NativeImageFinderDriver } from '../NativeImageFinder.js';
+import type { NativeImageMatch, NativeImageSearchOptions, NativeRegion, NativeTemplateRef } from '../types.js';
+import { loadNlMatcher, loadNut, type NutRegion } from './loadNut.js';
+
+export interface NutNativeImageFinderOptions {
+  templatesDir?: string;
+  confidence?: number;
+  enableNlMatcher?: boolean;
+}
+
+function toRegion(region: NutRegion): NativeRegion {
+  return {
+    x: region.left ?? region.x ?? 0,
+    y: region.top ?? region.y ?? 0,
+    width: region.width,
+    height: region.height
+  };
+}
+
+function templateName(template: string | NativeTemplateRef): string {
+  return typeof template === 'string' ? template : template.name;
+}
+
+export class NutNativeImageFinderDriver implements NativeImageFinderDriver {
+  private initialized = false;
+
+  constructor(private readonly options: NutNativeImageFinderOptions = {}) {}
+
+  async findTemplate(template: string | NativeTemplateRef, options: NativeImageSearchOptions = {}): Promise<NativeImageMatch | null> {
+    const nut = await this.initialize();
+    if (nut.screen.find === undefined || nut.imageResource === undefined) {
+      return null;
+    }
+
+    const resourcePath = await this.materializeTemplate(template);
+    const searchOptions = this.buildSearchOptions(options);
+
+    try {
+      const region = await nut.screen.find(nut.imageResource(resourcePath), searchOptions);
+      const match: NativeImageMatch = { region: toRegion(region) };
+      if (options.confidence !== undefined) match.confidence = options.confidence;
+      return match;
+    } catch {
+      return null;
+    }
+  }
+
+  private async initialize() {
+    const nut = await loadNut();
+    if (!this.initialized) {
+      if (this.options.enableNlMatcher ?? true) {
+        await loadNlMatcher();
+      }
+      if (this.options.templatesDir !== undefined && nut.screen.config !== undefined) {
+        nut.screen.config.resourceDirectory = this.options.templatesDir;
+      }
+      if (this.options.confidence !== undefined && nut.screen.config !== undefined) {
+        nut.screen.config.confidence = this.options.confidence;
+      }
+      this.initialized = true;
+    }
+    return nut;
+  }
+
+  private buildSearchOptions(options: NativeImageSearchOptions): Record<string, unknown> | undefined {
+    const searchOptions: Record<string, unknown> = {};
+    if (options.searchRegion !== undefined) {
+      searchOptions.searchRegion = {
+        left: options.searchRegion.x,
+        top: options.searchRegion.y,
+        width: options.searchRegion.width,
+        height: options.searchRegion.height
+      };
+    }
+    if (options.confidence !== undefined) {
+      searchOptions.confidence = options.confidence;
+    }
+    return Object.keys(searchOptions).length === 0 ? undefined : searchOptions;
+  }
+
+  private async materializeTemplate(template: string | NativeTemplateRef): Promise<string> {
+    if (typeof template === 'string') {
+      return this.options.templatesDir === undefined ? template : path.join(this.options.templatesDir, template);
+    }
+
+    if (template.buffer === undefined) {
+      return this.options.templatesDir === undefined ? template.name : path.join(this.options.templatesDir, template.name);
+    }
+
+    const fileName = `${template.name.replace(/[^a-z0-9._-]/gi, '_')}`;
+    const filePath = path.join(os.tmpdir(), fileName);
+    await fs.writeFile(filePath, template.buffer);
+    return filePath;
+  }
+}