@epsilon-asi/actors 0.0.22 → 0.0.32

package/src/native/NativeFileDialogService.ts

@@ -0,0 +1,138 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { Logger } from '../logging/Logger.js';
+import { NativeFileDialogError } from './errors.js';
+import type { NativeImageFinder, NativeKeyboard, NativeMouse, SelectFileOptions } from './types.js';
+import { centerOf } from './utils/geometry.js';
+import { redactPath } from './utils/redactNative.js';
+
+export interface FileDialogAccessibilityStrategy {
+  selectFile(filePath: string, options: SelectFileOptions): Promise<void>;
+}
+
+export interface NativeFileDialogServiceDependencies {
+  keyboard: NativeKeyboard;
+  mouse?: NativeMouse;
+  images?: NativeImageFinder;
+  accessibility?: FileDialogAccessibilityStrategy;
+  logger?: Logger;
+  defaultTimeoutMs?: number;
+  revealFilePathsInLogs?: boolean;
+}
+
+export class DefaultNativeFileDialogService {
+  constructor(private readonly deps: NativeFileDialogServiceDependencies) {}
+
+  async selectFile(filePath: string, options: SelectFileOptions = {}): Promise<void> {
+    const absolutePath = path.resolve(filePath);
+    await this.assertFileExists(absolutePath);
+
+    const strategy = options.strategy ?? 'auto';
+    const failures: unknown[] = [];
+
+    if (strategy === 'applescript' || strategy === 'auto') {
+      if (this.deps.accessibility !== undefined) {
+        try {
+          await this.deps.accessibility.selectFile(absolutePath, options);
+          this.logSuccess('applescript', absolutePath);
+          return;
+        } catch (error) {
+          failures.push(error);
+          if (strategy === 'applescript') throw this.wrapFailure('applescript', absolutePath, failures);
+        }
+      } else if (strategy === 'applescript') {
+        throw new NativeFileDialogError('AppleScript file-dialog strategy is not available.', { strategy });
+      }
+    }
+
+    if (strategy === 'visual' || strategy === 'auto') {
+      if (this.deps.images !== undefined && this.deps.mouse !== undefined) {
+        try {
+          await this.selectFileVisually(absolutePath, options);
+          this.logSuccess('visual', absolutePath);
+          return;
+        } catch (error) {
+          failures.push(error);
+          if (strategy === 'visual') throw this.wrapFailure('visual', absolutePath, failures);
+        }
+      } else if (strategy === 'visual') {
+        throw new NativeFileDialogError('Visual file-dialog strategy requires image finder and native mouse dependencies.', { strategy });
+      }
+    }
+
+    if (strategy === 'keyboard' || strategy === 'auto') {
+      try {
+        await this.selectFileWithKeyboard(absolutePath, options);
+        this.logSuccess('keyboard', absolutePath);
+        return;
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+
+    throw this.wrapFailure(strategy, absolutePath, failures);
+  }
+
+  private async assertFileExists(filePath: string): Promise<void> {
+    const stat = await fs.stat(filePath).catch(() => null);
+    if (stat === null || !stat.isFile()) {
+      throw new NativeFileDialogError('Cannot select file because the path does not exist or is not a file.', {
+        filePath: redactPath(filePath, this.deps.revealFilePathsInLogs)
+      });
+    }
+  }
+
+  private async selectFileVisually(filePath: string, options: SelectFileOptions): Promise<void> {
+    if (this.deps.images === undefined || this.deps.mouse === undefined) {
+      throw new NativeFileDialogError('Visual file-dialog strategy requires image finder and native mouse dependencies.');
+    }
+
+    if (options.inputFieldTemplate !== undefined) {
+      const input = await this.deps.images.waitForTemplate(options.inputFieldTemplate, this.imageSearchOptions(options));
+      await this.deps.mouse.click(centerOf(input.region));
+    } else {
+      await this.deps.keyboard.pressShortcut(['Meta', 'Shift', 'G']);
+    }
+
+    await this.deps.keyboard.type(filePath);
+    await this.deps.keyboard.pressKey('Enter');
+
+    if ((options.clickOpen ?? true) && options.openButtonTemplate !== undefined) {
+      const openButton = await this.deps.images.waitForTemplate(options.openButtonTemplate, this.imageSearchOptions(options));
+      await this.deps.mouse.click(centerOf(openButton.region));
+    } else if (options.clickOpen ?? true) {
+      await this.deps.keyboard.pressKey('Enter');
+    }
+  }
+
+  private async selectFileWithKeyboard(filePath: string, options: SelectFileOptions): Promise<void> {
+    await this.deps.keyboard.pressShortcut(['Meta', 'Shift', 'G']);
+    await this.deps.keyboard.type(filePath);
+    await this.deps.keyboard.pressKey('Enter');
+    if (options.clickOpen ?? true) {
+      await this.deps.keyboard.pressKey('Enter');
+    }
+  }
+
+  private imageSearchOptions(options: SelectFileOptions) {
+    const searchOptions: { timeoutMs?: number; intervalMs?: number } = {};
+    if (options.timeoutMs !== undefined) searchOptions.timeoutMs = options.timeoutMs;
+    if (options.intervalMs !== undefined) searchOptions.intervalMs = options.intervalMs;
+    return searchOptions;
+  }
+
+  private wrapFailure(strategy: string, filePath: string, failures: unknown[]): NativeFileDialogError {
+    return new NativeFileDialogError('Failed to select a file in the native file dialog.', {
+      strategy,
+      filePath: redactPath(filePath, this.deps.revealFilePathsInLogs),
+      failures
+    });
+  }
+
+  private logSuccess(strategy: string, filePath: string): void {
+    this.deps.logger?.debug('Selected file in native dialog.', {
+      strategy,
+      filePath: redactPath(filePath, this.deps.revealFilePathsInLogs)
+    });
+  }
+}

package/src/native/NativeImageFinder.ts

@@ -0,0 +1,33 @@
+import type { NativeImageFinder, NativeImageMatch, NativeImageSearchOptions, NativeTemplateRef } from './types.js';
+import { NativeImageNotFoundError } from './errors.js';
+import { waitFor } from './utils/waitFor.js';
+
+export interface NativeImageFinderDriver {
+  findTemplate(template: string | NativeTemplateRef, options?: NativeImageSearchOptions): Promise<NativeImageMatch | null>;
+}
+
+export class DefaultNativeImageFinder implements NativeImageFinder {
+  constructor(private readonly driver: NativeImageFinderDriver, private readonly defaultTimeoutMs = 15_000) {}
+
+  async findTemplate(template: string | NativeTemplateRef, options?: NativeImageSearchOptions): Promise<NativeImageMatch | null> {
+    return this.driver.findTemplate(template, options);
+  }
+
+  async waitForTemplate(template: string | NativeTemplateRef, options: NativeImageSearchOptions = {}): Promise<NativeImageMatch> {
+    try {
+      return await waitFor(
+        () => this.findTemplate(template, options),
+        {
+          timeoutMs: options.timeoutMs ?? this.defaultTimeoutMs,
+          intervalMs: options.intervalMs ?? 100,
+          description: `native image template ${typeof template === 'string' ? template : template.name}`
+        }
+      );
+    } catch (error) {
+      throw new NativeImageNotFoundError({
+        template: typeof template === 'string' ? template : template.name,
+        cause: error
+      });
+    }
+  }
+}

package/src/native/NativeKeyboard.ts

@@ -0,0 +1,18 @@
+import type { NativeKeyboardDriver } from './drivers.js';
+import type { NativeKeyboard, NativeKeyboardTypeOptions } from './types.js';
+
+export class DefaultNativeKeyboard implements NativeKeyboard {
+  constructor(private readonly driver: NativeKeyboardDriver) {}
+
+  async type(text: string, options: NativeKeyboardTypeOptions = {}): Promise<void> {
+    await this.driver.type(text, options.delayMs === undefined ? undefined : { delayMs: options.delayMs });
+  }
+
+  async pressKey(key: string): Promise<void> {
+    await this.driver.pressKey(key);
+  }
+
+  async pressShortcut(keys: readonly string[]): Promise<void> {
+    await this.driver.pressShortcut(keys);
+  }
+}

package/src/native/NativeMouse.ts

@@ -0,0 +1,116 @@
+import { path as ghostCursorPath } from 'ghost-cursor';
+import type { PageLike } from '../browser/PuppeteerLike.js';
+import type { NativeMouseDriver } from './drivers.js';
+import type {
+  BrowserPoint,
+  NativeMouse,
+  NativeMouseClickOptions,
+  NativeMouseMoveOptions,
+  NativePoint,
+  NativeRegion,
+  ScreenPoint
+} from './types.js';
+import { centerOf, clampPointToRegion, randomPointInRegion, roundPoint } from './utils/geometry.js';
+
+export type NativeRandomFunction = () => number;
+export type NativeSleepFunction = (ms: number) => Promise<void>;
+export type PathGenerator = (from: NativePoint, to: NativePoint, options?: { moveSpeed?: number }) => NativePoint[];
+
+export interface HumanizedNativeMouseOptions {
+  jitterPixels?: number;
+  minJitterPixels?: number;
+  moveSpeed?: number;
+  random?: NativeRandomFunction;
+  sleep?: NativeSleepFunction;
+  pathGenerator?: PathGenerator;
+  coordinateMapper: {
+    browserToScreen(point: BrowserPoint, options?: { page?: PageLike }): Promise<ScreenPoint>;
+  };
+}
+
+const defaultSleep: NativeSleepFunction = async ms => {
+  if (ms <= 0) return;
+  await new Promise<void>(resolve => setTimeout(resolve, ms));
+};
+
+function defaultPathGenerator(from: NativePoint, to: NativePoint, options?: { moveSpeed?: number }): NativePoint[] {
+  const pathOptions = options?.moveSpeed === undefined ? undefined : { moveSpeed: options.moveSpeed };
+  return ghostCursorPath(from, to, pathOptions) as NativePoint[];
+}
+
+function normalizeJitter(minJitterPixels: number | undefined, jitterPixels: number | undefined): { min: number; max: number } {
+  const max = Math.max(0, jitterPixels ?? 3);
+  const min = Math.min(max, Math.max(0, minJitterPixels ?? Math.min(2, max)));
+  return { min, max };
+}
+
+export class HumanizedNativeMouse implements NativeMouse {
+  private readonly random: NativeRandomFunction;
+  private readonly sleep: NativeSleepFunction;
+  private readonly pathGenerator: PathGenerator;
+  private readonly jitterPixels: number;
+  private readonly minJitterPixels: number;
+  private readonly moveSpeed: number | undefined;
+
+  constructor(private readonly driver: NativeMouseDriver, private readonly options: HumanizedNativeMouseOptions) {
+    this.random = options.random ?? Math.random;
+    this.sleep = options.sleep ?? defaultSleep;
+    this.pathGenerator = options.pathGenerator ?? defaultPathGenerator;
+    this.jitterPixels = options.jitterPixels ?? 3;
+    this.minJitterPixels = options.minJitterPixels ?? 2;
+    this.moveSpeed = options.moveSpeed;
+  }
+
+  async moveTo(point: ScreenPoint, options: NativeMouseMoveOptions = {}): Promise<void> {
+    const current = await this.driver.getPosition();
+    const target = roundPoint(this.applyJitter(point, options));
+
+    if (options.disableHumanPath === true) {
+      await this.driver.move(target);
+      return;
+    }
+
+    const moveSpeed = options.moveSpeed ?? this.moveSpeed;
+    const route = this.pathGenerator(current, target, moveSpeed === undefined ? undefined : { moveSpeed });
+    const points = route.length === 0 ? [target] : route;
+
+    for (const [index, routePoint] of points.entries()) {
+      const isLast = index === points.length - 1;
+      const nextPoint = isLast ? target : roundPoint(this.applyJitter(routePoint, options));
+      await this.driver.move(nextPoint);
+    }
+  }
+
+  async click(point: ScreenPoint, options: NativeMouseClickOptions = {}): Promise<void> {
+    await this.moveTo(point, options);
+    await this.sleep(options.delayBeforeClickMs ?? 0);
+    await this.driver.click(options.button ?? 'left');
+    await this.sleep(options.delayAfterMoveMs ?? 0);
+  }
+
+  async clickRegion(region: NativeRegion, options: NativeMouseClickOptions = {}): Promise<void> {
+    const padding = options.regionPaddingPx ?? 4;
+    const point = randomPointInRegion(region, this.random, padding);
+    const target = options.precise === true ? point : clampPointToRegion(this.applyJitter(point, options), region);
+    await this.click(roundPoint(target), { ...options, precise: true });
+  }
+
+  async clickBrowserPoint(page: PageLike, point: BrowserPoint, options: NativeMouseClickOptions = {}): Promise<void> {
+    const screenPoint = await this.options.coordinateMapper.browserToScreen(point, { page });
+    await this.click(screenPoint, options);
+  }
+
+  private applyJitter(point: NativePoint, options: NativeMouseMoveOptions): NativePoint {
+    if (options.precise === true) return point;
+
+    const { min, max } = normalizeJitter(options.minJitterPixels ?? this.minJitterPixels, options.jitterPixels ?? this.jitterPixels);
+    if (max <= 0) return point;
+
+    const distance = min + this.random() * (max - min);
+    const angle = this.random() * Math.PI * 2;
+    return {
+      x: point.x + Math.cos(angle) * distance,
+      y: point.y + Math.sin(angle) * distance
+    };
+  }
+}

package/src/native/NativeWindowService.ts

@@ -0,0 +1,229 @@
+import type { Logger } from '../logging/Logger.js';
+import type { NativeScreenDriver, NativeWindowDriver, NativeWindowHandle } from './drivers.js';
+import { NativeAutomationError, NativeWindowNotFoundError } from './errors.js';
+import { matchesWindow, matcherToString } from './WindowMatcher.js';
+import type {
+  EnsureWindowInViewOptions,
+  NativeImageFinder,
+  NativeMouse,
+  NativeRegion,
+  NativeWindowInfo,
+  WaitOptions,
+  WindowButtonOptions,
+  WindowMatcher
+} from './types.js';
+import { centerOf, visibleEnough } from './utils/geometry.js';
+import { waitFor } from './utils/waitFor.js';
+
+export interface NativeWindowServiceDependencies {
+  driver: NativeWindowDriver;
+  screen: NativeScreenDriver;
+  mouse?: NativeMouse;
+  images?: NativeImageFinder;
+  logger?: Logger;
+  defaultTimeoutMs?: number;
+}
+
+export class DefaultNativeWindowService {
+  private readonly defaultTimeoutMs: number;
+
+  constructor(private readonly deps: NativeWindowServiceDependencies) {
+    this.defaultTimeoutMs = deps.defaultTimeoutMs ?? 15_000;
+  }
+
+  async list(): Promise<NativeWindowInfo[]> {
+    const handles = await this.deps.driver.list();
+    return Promise.all(handles.map(handle => handle.info()));
+  }
+
+  async find(matcher: WindowMatcher, options: WaitOptions = {}): Promise<NativeWindowInfo | null> {
+    if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+      try {
+        return await this.waitFor(matcher, options);
+      } catch (error) {
+        if (error instanceof NativeWindowNotFoundError) return null;
+        throw error;
+      }
+    }
+
+    const handle = await this.findHandle(matcher);
+    return handle === null ? null : handle.info();
+  }
+
+  async waitFor(matcher: WindowMatcher, options: WaitOptions = {}): Promise<NativeWindowInfo> {
+    try {
+      const handle = await this.waitForHandle(matcher, options);
+      return handle.info();
+    } catch (error) {
+      if (error instanceof NativeWindowNotFoundError) throw error;
+      throw new NativeWindowNotFoundError({ matcher: matcherToString(matcher), cause: error });
+    }
+  }
+
+  async isOpen(matcher: WindowMatcher): Promise<boolean> {
+    return (await this.findHandle(matcher)) !== null;
+  }
+
+  async focus(matcher: WindowMatcher): Promise<NativeWindowInfo> {
+    const handle = await this.waitForHandle(matcher);
+    const before = await handle.info();
+    if (before.isMinimized === true) {
+      await handle.restore();
+    }
+    await handle.focus();
+    return this.refreshHandleInfo(handle);
+  }
+
+  async ensureInView(matcher: WindowMatcher, options: EnsureWindowInViewOptions = {}): Promise<NativeWindowInfo> {
+    const restore = options.restore ?? true;
+    const focus = options.focus ?? true;
+    const moveIntoPrimaryDisplay = options.moveIntoPrimaryDisplay ?? true;
+    const minimumVisibleWidth = options.minimumVisibleWidth ?? 100;
+    const minimumVisibleHeight = options.minimumVisibleHeight ?? 80;
+
+    const handle = await this.waitForHandle(matcher, options);
+    let info = await handle.info();
+
+    if (restore && info.isMinimized === true) {
+      await handle.restore();
+      info = await handle.info();
+    }
+
+    if (focus) {
+      await handle.focus();
+      info = await handle.info();
+    }
+
+    if (moveIntoPrimaryDisplay) {
+      const primaryDisplay: NativeRegion = {
+        x: 0,
+        y: 0,
+        width: await this.deps.screen.width(),
+        height: await this.deps.screen.height()
+      };
+
+      if (!visibleEnough(info.region, primaryDisplay, minimumVisibleWidth, minimumVisibleHeight)) {
+        const target = {
+          x: Math.max(0, Math.min(info.region.x, Math.max(0, primaryDisplay.width - info.region.width))),
+          y: Math.max(0, Math.min(info.region.y, Math.max(0, primaryDisplay.height - info.region.height)))
+        };
+        await handle.move(target);
+        info = await handle.info();
+      }
+    }
+
+    return info;
+  }
+
+  async setFullscreen(matcher: WindowMatcher, fullscreen: boolean, options: WindowButtonOptions = {}): Promise<void> {
+    const handle = await this.waitForHandle(matcher, options);
+    const info = await handle.info();
+
+    if (info.isFullscreen === fullscreen) {
+      return;
+    }
+
+    if (handle.setFullscreen !== undefined) {
+      await handle.setFullscreen(fullscreen);
+      return;
+    }
+
+    if (handle.toggleFullscreen !== undefined) {
+      await handle.toggleFullscreen();
+      return;
+    }
+
+    if ((options.strategy ?? 'auto') !== 'accessibility' && this.deps.images !== undefined && this.deps.mouse !== undefined && options.fullscreenButtonTemplate !== undefined) {
+      await this.clickWindowButtonTemplate(info.region, options.fullscreenButtonTemplate, options);
+      return;
+    }
+
+    throw new NativeAutomationError('Window fullscreen control is unavailable for the matched window.', {
+      matcher: matcherToString(matcher),
+      strategy: options.strategy ?? 'auto'
+    });
+  }
+
+  async toggleFullscreen(matcher: WindowMatcher, options: WindowButtonOptions = {}): Promise<void> {
+    const handle = await this.waitForHandle(matcher, options);
+    const info = await handle.info();
+
+    if (handle.toggleFullscreen !== undefined) {
+      await handle.toggleFullscreen();
+      return;
+    }
+
+    if (handle.setFullscreen !== undefined && info.isFullscreen !== undefined) {
+      await handle.setFullscreen(!info.isFullscreen);
+      return;
+    }
+
+    if ((options.strategy ?? 'auto') !== 'accessibility' && this.deps.images !== undefined && this.deps.mouse !== undefined && options.fullscreenButtonTemplate !== undefined) {
+      await this.clickWindowButtonTemplate(info.region, options.fullscreenButtonTemplate, options);
+      return;
+    }
+
+    throw new NativeAutomationError('Window fullscreen toggle is unavailable for the matched window.', {
+      matcher: matcherToString(matcher),
+      strategy: options.strategy ?? 'auto'
+    });
+  }
+
+  async minimize(matcher: WindowMatcher): Promise<void> {
+    const handle = await this.waitForHandle(matcher);
+    await handle.minimize();
+  }
+
+  async restore(matcher: WindowMatcher): Promise<void> {
+    const handle = await this.waitForHandle(matcher);
+    await handle.restore();
+  }
+
+  private async findHandle(matcher: WindowMatcher): Promise<NativeWindowHandle | null> {
+    const handles = await this.deps.driver.list();
+    for (const handle of handles) {
+      const info = await handle.info();
+      if (matchesWindow(info, matcher)) {
+        return handle;
+      }
+    }
+    return null;
+  }
+
+  private async waitForHandle(matcher: WindowMatcher, options: WaitOptions = {}): Promise<NativeWindowHandle> {
+    try {
+      return await waitFor(
+        () => this.findHandle(matcher),
+        {
+          timeoutMs: options.timeoutMs ?? this.defaultTimeoutMs,
+          intervalMs: options.intervalMs ?? 100,
+          description: `native window (${matcherToString(matcher)})`
+        }
+      );
+    } catch (error) {
+      throw new NativeWindowNotFoundError({ matcher: matcherToString(matcher), cause: error });
+    }
+  }
+
+  private async refreshHandleInfo(handle: NativeWindowHandle): Promise<NativeWindowInfo> {
+    return handle.info();
+  }
+
+  private async clickWindowButtonTemplate(region: NativeRegion, template: string, options: WindowButtonOptions): Promise<void> {
+    if (this.deps.images === undefined || this.deps.mouse === undefined) {
+      throw new NativeAutomationError('Visual window button strategy requires image finder and native mouse dependencies.');
+    }
+    const padding = options.searchRegionPaddingPx ?? 96;
+    const searchRegion: NativeRegion = {
+      x: region.x,
+      y: region.y,
+      width: Math.min(region.width, padding),
+      height: Math.min(region.height, padding)
+    };
+    const imageOptions: { searchRegion: NativeRegion; timeoutMs?: number; intervalMs?: number } = { searchRegion };
+    if (options.timeoutMs !== undefined) imageOptions.timeoutMs = options.timeoutMs;
+    if (options.intervalMs !== undefined) imageOptions.intervalMs = options.intervalMs;
+    const match = await this.deps.images.waitForTemplate(template, imageOptions);
+    await this.deps.mouse.click(centerOf(match.region));
+  }
+}

package/src/native/UnsupportedNativeAutomation.ts

@@ -0,0 +1,92 @@
+import type {
+  BrowserPoint,
+  CalibrationOptions,
+  CoordinateMapOptions,
+  CoordinateTransform,
+  NativeAutomation,
+  NativeFileDialogService,
+  NativeImageFinder,
+  NativeImageMatch,
+  NativeImageSearchOptions,
+  NativeKeyboard,
+  NativeMouse,
+  NativeMouseClickOptions,
+  NativeMouseMoveOptions,
+  NativeRegion,
+  NativeTemplateRef,
+  NativeWindowInfo,
+  NativeWindowService,
+  ScreenPoint,
+  SelectFileOptions,
+  WaitOptions,
+  WindowButtonOptions,
+  WindowMatcher
+} from './types.js';
+import { DefaultNativeActionRegistry, registerDefaultNativeActions } from './NativeActionRegistry.js';
+import { UnsupportedPlatformError } from './errors.js';
+import type { Logger } from '../logging/Logger.js';
+import type { PageLike } from '../browser/PuppeteerLike.js';
+
+class UnsupportedNativeWindowService implements NativeWindowService {
+  constructor(private readonly platform: NodeJS.Platform) {}
+  async list(): Promise<NativeWindowInfo[]> { throw new UnsupportedPlatformError(this.platform); }
+  async find(_matcher: WindowMatcher, _options?: WaitOptions): Promise<NativeWindowInfo | null> { throw new UnsupportedPlatformError(this.platform); }
+  async waitFor(_matcher: WindowMatcher, _options?: WaitOptions): Promise<NativeWindowInfo> { throw new UnsupportedPlatformError(this.platform); }
+  async isOpen(_matcher: WindowMatcher): Promise<boolean> { throw new UnsupportedPlatformError(this.platform); }
+  async focus(_matcher: WindowMatcher): Promise<NativeWindowInfo> { throw new UnsupportedPlatformError(this.platform); }
+  async ensureInView(_matcher: WindowMatcher): Promise<NativeWindowInfo> { throw new UnsupportedPlatformError(this.platform); }
+  async setFullscreen(_matcher: WindowMatcher, _fullscreen: boolean, _options?: WindowButtonOptions): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async toggleFullscreen(_matcher: WindowMatcher, _options?: WindowButtonOptions): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async minimize(_matcher: WindowMatcher): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async restore(_matcher: WindowMatcher): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+}
+
+class UnsupportedNativeFileDialogService implements NativeFileDialogService {
+  constructor(private readonly platform: NodeJS.Platform) {}
+  async selectFile(_filePath: string, _options?: SelectFileOptions): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+}
+
+class UnsupportedNativeMouse implements NativeMouse {
+  constructor(private readonly platform: NodeJS.Platform) {}
+  async moveTo(_point: ScreenPoint, _options?: NativeMouseMoveOptions): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async click(_point: ScreenPoint, _options?: NativeMouseClickOptions): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async clickRegion(_region: NativeRegion, _options?: NativeMouseClickOptions): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async clickBrowserPoint(_page: PageLike, _point: BrowserPoint, _options?: NativeMouseClickOptions): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+}
+
+class UnsupportedNativeKeyboard implements NativeKeyboard {
+  constructor(private readonly platform: NodeJS.Platform) {}
+  async type(_text: string): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async pressKey(_key: string): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+  async pressShortcut(_keys: readonly string[]): Promise<void> { throw new UnsupportedPlatformError(this.platform); }
+}
+
+class UnsupportedNativeCoordinateMapper {
+  constructor(private readonly platform: NodeJS.Platform) {}
+  async calibrate(_page: PageLike, _options?: CalibrationOptions): Promise<CoordinateTransform> { throw new UnsupportedPlatformError(this.platform); }
+  async browserToScreen(_point: BrowserPoint, _options?: CoordinateMapOptions): Promise<ScreenPoint> { throw new UnsupportedPlatformError(this.platform); }
+  async screenToBrowser(_point: ScreenPoint, _options?: CoordinateMapOptions): Promise<BrowserPoint> { throw new UnsupportedPlatformError(this.platform); }
+  invalidate(): void {}
+}
+
+class UnsupportedNativeImageFinder implements NativeImageFinder {
+  constructor(private readonly platform: NodeJS.Platform) {}
+  async findTemplate(_template: string | NativeTemplateRef, _options?: NativeImageSearchOptions): Promise<NativeImageMatch | null> { throw new UnsupportedPlatformError(this.platform); }
+  async waitForTemplate(_template: string | NativeTemplateRef, _options?: NativeImageSearchOptions): Promise<NativeImageMatch> { throw new UnsupportedPlatformError(this.platform); }
+}
+
+export function createUnsupportedNativeAutomation(platform: NodeJS.Platform, logger: Logger): NativeAutomation {
+  const automation = {
+    windows: new UnsupportedNativeWindowService(platform),
+    fileDialogs: new UnsupportedNativeFileDialogService(platform),
+    mouse: new UnsupportedNativeMouse(platform),
+    keyboard: new UnsupportedNativeKeyboard(platform),
+    coordinates: new UnsupportedNativeCoordinateMapper(platform),
+    images: new UnsupportedNativeImageFinder(platform),
+    actions: undefined as unknown as DefaultNativeActionRegistry
+  } satisfies Omit<NativeAutomation, 'actions'> & { actions: DefaultNativeActionRegistry };
+
+  const registry = new DefaultNativeActionRegistry(() => ({ automation, logger }));
+  automation.actions = registerDefaultNativeActions(registry, automation, logger);
+  return automation;
+}

package/src/native/WindowMatcher.ts

@@ -0,0 +1,31 @@
+import type { NativeWindowInfo, WindowMatcher } from './types.js';
+
+function matchesRegex(value: string, regex: RegExp | string): boolean {
+  const expression = typeof regex === 'string' ? new RegExp(regex) : regex;
+  return expression.test(value);
+}
+
+function matchesOptional(actual: string | undefined, expected: string | undefined): boolean {
+  return expected === undefined || actual === expected;
+}
+
+export function matchesWindow(info: NativeWindowInfo, matcher: WindowMatcher): boolean {
+  if (!matchesOptional(info.appName, matcher.appName)) return false;
+  if (!matchesOptional(info.bundleId, matcher.bundleId)) return false;
+  if (!matchesOptional(info.role, matcher.role)) return false;
+  if (matcher.title !== undefined && info.title !== matcher.title) return false;
+  if (matcher.titleIncludes !== undefined && !info.title.includes(matcher.titleIncludes)) return false;
+  if (matcher.titleRegex !== undefined && !matchesRegex(info.title, matcher.titleRegex)) return false;
+  return true;
+}
+
+export function matcherToString(matcher: WindowMatcher): string {
+  const parts: string[] = [];
+  if (matcher.appName !== undefined) parts.push(`app=${matcher.appName}`);
+  if (matcher.bundleId !== undefined) parts.push(`bundle=${matcher.bundleId}`);
+  if (matcher.title !== undefined) parts.push(`title=${matcher.title}`);
+  if (matcher.titleIncludes !== undefined) parts.push(`titleIncludes=${matcher.titleIncludes}`);
+  if (matcher.titleRegex !== undefined) parts.push(`titleRegex=${String(matcher.titleRegex)}`);
+  if (matcher.role !== undefined) parts.push(`role=${matcher.role}`);
+  return parts.length === 0 ? '<any window>' : parts.join(', ');
+}