@epsilon-asi/actors 0.0.22 → 0.0.33

package/tests/fixtures/native/FakeNativeAutomation.ts

@@ -0,0 +1,138 @@
+import type { PageLike } from '../../../src/browser/PuppeteerLike.js';
+import { DefaultNativeActionRegistry, registerDefaultNativeActions } from '../../../src/native/NativeActionRegistry.js';
+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 '../../../src/native/types.js';
+import type { Logger } from '../../../src/logging/Logger.js';
+import { MemoryLogger } from '../../../src/logging/MemoryLogger.js';
+
+export class FakeNativeWindowService implements NativeWindowService {
+  windows: NativeWindowInfo[] = [];
+  focused: WindowMatcher[] = [];
+  minimized: WindowMatcher[] = [];
+  restored: WindowMatcher[] = [];
+  fullscreenCalls: Array<{ matcher: WindowMatcher; fullscreen: boolean }> = [];
+
+  async list(): Promise<NativeWindowInfo[]> { return this.windows; }
+  async find(matcher: WindowMatcher, _options?: WaitOptions): Promise<NativeWindowInfo | null> {
+    return this.windows.find(window => matcher.title === undefined || window.title === matcher.title) ?? null;
+  }
+  async waitFor(matcher: WindowMatcher, options?: WaitOptions): Promise<NativeWindowInfo> {
+    const found = await this.find(matcher, options);
+    if (found === null) throw new Error('Missing fake native window.');
+    return found;
+  }
+  async isOpen(matcher: WindowMatcher): Promise<boolean> { return (await this.find(matcher)) !== null; }
+  async focus(matcher: WindowMatcher): Promise<NativeWindowInfo> { this.focused.push(matcher); return this.waitFor(matcher); }
+  async ensureInView(matcher: WindowMatcher): Promise<NativeWindowInfo> { this.focused.push(matcher); return this.waitFor(matcher); }
+  async setFullscreen(matcher: WindowMatcher, fullscreen: boolean, _options?: WindowButtonOptions): Promise<void> { this.fullscreenCalls.push({ matcher, fullscreen }); }
+  async toggleFullscreen(matcher: WindowMatcher, _options?: WindowButtonOptions): Promise<void> { this.fullscreenCalls.push({ matcher, fullscreen: true }); }
+  async minimize(matcher: WindowMatcher): Promise<void> { this.minimized.push(matcher); }
+  async restore(matcher: WindowMatcher): Promise<void> { this.restored.push(matcher); }
+}
+
+export class FakeNativeFileDialogService implements NativeFileDialogService {
+  selected: Array<{ filePath: string; options?: SelectFileOptions }> = [];
+  async selectFile(filePath: string, options?: SelectFileOptions): Promise<void> {
+    const record: { filePath: string; options?: SelectFileOptions } = { filePath };
+    if (options !== undefined) record.options = options;
+    this.selected.push(record);
+  }
+}
+
+export class FakeNativeMouse implements NativeMouse {
+  moves: Array<{ point: ScreenPoint; options?: NativeMouseMoveOptions }> = [];
+  clicks: Array<{ point: ScreenPoint; options?: NativeMouseClickOptions }> = [];
+  regionClicks: Array<{ region: NativeRegion; options?: NativeMouseClickOptions }> = [];
+  browserClicks: Array<{ page: PageLike; point: BrowserPoint; options?: NativeMouseClickOptions }> = [];
+  async moveTo(point: ScreenPoint, options?: NativeMouseMoveOptions): Promise<void> { this.moves.push(options === undefined ? { point } : { point, options }); }
+  async click(point: ScreenPoint, options?: NativeMouseClickOptions): Promise<void> { this.clicks.push(options === undefined ? { point } : { point, options }); }
+  async clickRegion(region: NativeRegion, options?: NativeMouseClickOptions): Promise<void> { this.regionClicks.push(options === undefined ? { region } : { region, options }); }
+  async clickBrowserPoint(page: PageLike, point: BrowserPoint, options?: NativeMouseClickOptions): Promise<void> { this.browserClicks.push(options === undefined ? { page, point } : { page, point, options }); }
+}
+
+export class FakeNativeKeyboard implements NativeKeyboard {
+  typed: string[] = [];
+  pressed: string[] = [];
+  shortcuts: Array<readonly string[]> = [];
+  async type(text: string): Promise<void> { this.typed.push(text); }
+  async pressKey(key: string): Promise<void> { this.pressed.push(key); }
+  async pressShortcut(keys: readonly string[]): Promise<void> { this.shortcuts.push(keys); }
+}
+
+export class FakeNativeImageFinder implements NativeImageFinder {
+  matches = new Map<string, NativeImageMatch | null>();
+  async findTemplate(template: string | NativeTemplateRef, _options?: NativeImageSearchOptions): Promise<NativeImageMatch | null> {
+    return this.matches.get(typeof template === 'string' ? template : template.name) ?? null;
+  }
+  async waitForTemplate(template: string | NativeTemplateRef, options?: NativeImageSearchOptions): Promise<NativeImageMatch> {
+    const match = await this.findTemplate(template, options);
+    if (match === null) throw new Error('Missing fake image match.');
+    return match;
+  }
+}
+
+export class FakeNativeCoordinateMapper {
+  transform: CoordinateTransform = {
+    offsetX: 0,
+    offsetY: 0,
+    scaleX: 1,
+    scaleY: 1,
+    calibratedAt: Date.now(),
+    viewport: { innerWidth: 1000, innerHeight: 800, devicePixelRatio: 1 }
+  };
+  async calibrate(_page: PageLike, _options?: CalibrationOptions): Promise<CoordinateTransform> { return this.transform; }
+  async browserToScreen(point: BrowserPoint, _options?: CoordinateMapOptions): Promise<ScreenPoint> {
+    return { x: this.transform.offsetX + point.x * this.transform.scaleX, y: this.transform.offsetY + point.y * this.transform.scaleY };
+  }
+  async screenToBrowser(point: ScreenPoint, _options?: CoordinateMapOptions): Promise<BrowserPoint> {
+    return { x: (point.x - this.transform.offsetX) / this.transform.scaleX, y: (point.y - this.transform.offsetY) / this.transform.scaleY };
+  }
+  invalidate(): void {}
+}
+
+export interface FakeNativeAutomationParts extends NativeAutomation {
+  windows: FakeNativeWindowService;
+  fileDialogs: FakeNativeFileDialogService;
+  mouse: FakeNativeMouse;
+  keyboard: FakeNativeKeyboard;
+  images: FakeNativeImageFinder;
+  coordinates: FakeNativeCoordinateMapper;
+}
+
+export function createFakeNativeAutomation(logger: Logger = new MemoryLogger()): FakeNativeAutomationParts {
+  const automation = {
+    windows: new FakeNativeWindowService(),
+    fileDialogs: new FakeNativeFileDialogService(),
+    mouse: new FakeNativeMouse(),
+    keyboard: new FakeNativeKeyboard(),
+    images: new FakeNativeImageFinder(),
+    coordinates: new FakeNativeCoordinateMapper(),
+    actions: undefined as unknown as DefaultNativeActionRegistry
+  } satisfies FakeNativeAutomationParts;
+
+  const registry = new DefaultNativeActionRegistry(() => ({ automation, logger }));
+  automation.actions = registerDefaultNativeActions(registry, automation, logger);
+  return automation;
+}

package/tests/unit/browser/RuntimeConfig.native.test.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { normalizeRuntimeConfig } from '../../../src/browser/RuntimeConfig.js';
+
+function createUserDataDir(): string {
+  const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'paf-native-config-'));
+  fs.mkdirSync(path.join(userDataDir, 'Default'));
+  return userDataDir;
+}
+
+describe('native RuntimeConfig normalization', () => {
+  it('preserves backward compatibility when native config is omitted', () => {
+    const config = normalizeRuntimeConfig({
+      browser: {
+        mode: 'existing-profile',
+        userDataDir: createUserDataDir(),
+        profileDirectory: 'Default',
+        headless: false
+      }
+    });
+
+    expect(config.native).toBeUndefined();
+  });
+
+  it('normalizes native macOS automation defaults when opted in', () => {
+    const config = normalizeRuntimeConfig({
+      browser: {
+        mode: 'existing-profile',
+        userDataDir: createUserDataDir(),
+        profileDirectory: 'Default',
+        headless: false
+      },
+      native: {
+        templatesDir: '/tmp/templates'
+      }
+    });
+
+    expect(config.native).toMatchObject({
+      enabled: true,
+      platform: 'macos',
+      templatesDir: '/tmp/templates',
+      imageConfidence: 0.9,
+      mouse: {
+        jitterPixels: 3,
+        minJitterPixels: 2
+      },
+      macos: {
+        targetApplicationName: 'Google Chrome',
+        osascriptTimeoutMs: 15_000,
+        preferAppleScriptForWindows: true,
+        preferVisualTemplatesForDialogs: false
+      },
+      coordinateCalibration: {
+        enabled: true,
+        markerSizePx: 22,
+        timeoutMs: 15_000,
+        cacheTtlMs: 60_000
+      }
+    });
+  });
+});

package/tests/unit/core/ActorRunner.native.test.ts

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { BrowserFactory } from '../../../src/browser/BrowserFactory.js';
+import { BrowserSession } from '../../../src/browser/BrowserSession.js';
+import type { RuntimeConfig } from '../../../src/browser/RuntimeConfig.js';
+import { defineActor } from '../../../src/core/defineActor.js';
+import { ActorRunner } from '../../../src/core/ActorRunner.js';
+import { PuppeteerPageAdapter } from '../../../src/interaction/PageAdapter.js';
+import { MemoryLogger } from '../../../src/logging/MemoryLogger.js';
+import type { NativeAutomation } from '../../../src/native/types.js';
+import { FakeHumanInteractor } from '../../fixtures/FakeCursor.js';
+import { FakeBrowser, FakePage } from '../../fixtures/FakePage.js';
+import { createFakeNativeAutomation } from '../../fixtures/native/FakeNativeAutomation.js';
+
+class StaticBrowserFactory extends BrowserFactory {
+  constructor(private readonly session: BrowserSession) {
+    super();
+  }
+
+  override async launch(): Promise<BrowserSession> {
+    return this.session;
+  }
+}
+
+function createConfig(): RuntimeConfig {
+  const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'paf-native-runner-'));
+  fs.mkdirSync(path.join(userDataDir, 'Default'));
+  return {
+    browser: {
+      mode: 'existing-profile',
+      userDataDir,
+      profileDirectory: 'Default',
+      headless: false
+    }
+  };
+}
+
+describe('ActorRunner native automation integration', () => {
+  it('injects context.native from the configured nativeAutomationFactory', async () => {
+    const config = createConfig();
+    const page = new FakePage();
+    const browser = new FakeBrowser([page]);
+    const session = new BrowserSession(browser, browser.context, page, config.browser);
+    const native = createFakeNativeAutomation();
+    native.windows.windows = [{ title: 'Chrome', appName: 'Google Chrome', region: { x: 0, y: 0, width: 100, height: 100 } }];
+
+    const runner = new ActorRunner({
+      config,
+      browserFactory: new StaticBrowserFactory(session),
+      loginFlow: { ensureAuthenticated: async () => undefined } as never,
+      logger: new MemoryLogger(),
+      interactorFactory: () => new FakeHumanInteractor(),
+      pageAdapterFactory: pageLike => new PuppeteerPageAdapter(pageLike),
+      nativeAutomationFactory: () => native as NativeAutomation
+    });
+
+    const actor = defineActor({
+      id: 'example',
+      baseUrl: 'https://example.com',
+      tasks: {
+        checkWindow: async context => context.native.windows.isOpen({ title: 'Chrome' })
+      }
+    });
+
+    await expect(runner.run(actor, 'checkWindow')).resolves.toBe(true);
+  });
+});

package/tests/unit/native/MacOSAppleScriptClient.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import type { AppleScriptExecutor } from '../../../src/native/drivers.js';
+import { MacOSAppleScriptClient } from '../../../src/native/macos/MacOSAppleScriptClient.js';
+
+class FakeExecutor implements AppleScriptExecutor {
+  scripts: string[] = [];
+  result = '';
+  async execute(script: string): Promise<string> {
+    this.scripts.push(script);
+    return this.result;
+  }
+}
+
+describe('MacOSAppleScriptClient', () => {
+  it('escapes app names, titles, and file paths in generated scripts', async () => {
+    const executor = new FakeExecutor();
+    const client = new MacOSAppleScriptClient({ executor });
+
+    await client.setFullscreen({ appName: 'Google "Chrome"', title: 'A "quoted" window' }, true);
+    await client.selectFileInOpenDialog('/Users/me/A "quoted" file.pdf', 'Google "Chrome"');
+
+    expect(executor.scripts[0]).toContain('process "Google \\"Chrome\\""');
+    expect(executor.scripts[0]).toContain('"A \\"quoted\\" window"');
+    expect(executor.scripts[1]).toContain('set targetPath to "/Users/me/A \\"quoted\\" file.pdf"');
+  });
+
+  it('parses boolean window-open output', async () => {
+    const executor = new FakeExecutor();
+    executor.result = 'true';
+    const client = new MacOSAppleScriptClient({ executor });
+
+    await expect(client.isWindowOpen({ appName: 'Google Chrome', titleIncludes: 'Upwork' })).resolves.toBe(true);
+    expect(executor.scripts[0]).toContain('name of candidateWindow contains "Upwork"');
+  });
+});

package/tests/unit/native/NativeActionRegistry.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { DefaultNativeActionRegistry, defineNativeAction } from '../../../src/native/NativeActionRegistry.js';
+import { NativeAutomationError } from '../../../src/native/errors.js';
+import { MemoryLogger } from '../../../src/logging/MemoryLogger.js';
+import { createFakeNativeAutomation } from '../../fixtures/native/FakeNativeAutomation.js';
+
+describe('DefaultNativeActionRegistry', () => {
+  it('registers, lists, and runs typed native actions', async () => {
+    const logger = new MemoryLogger();
+    const automation = createFakeNativeAutomation(logger);
+    const registry = new DefaultNativeActionRegistry(() => ({ automation, logger }));
+
+    registry.register(defineNativeAction<{ value: number }, number>({
+      name: 'math.double',
+      description: 'Double a number.',
+      run: async (_context, input) => input.value * 2
+    }));
+
+    expect(registry.list()).toEqual([{ name: 'math.double', description: 'Double a number.' }]);
+    await expect(registry.run('math.double', { value: 21 })).resolves.toBe(42);
+  });
+
+  it('rejects duplicate and missing actions clearly', () => {
+    const logger = new MemoryLogger();
+    const automation = createFakeNativeAutomation(logger);
+    const registry = new DefaultNativeActionRegistry(() => ({ automation, logger }));
+    const action = defineNativeAction({ name: 'x', run: async () => undefined });
+
+    registry.register(action);
+
+    expect(() => registry.register(action)).toThrow(NativeAutomationError);
+    expect(() => registry.get('missing')).toThrow(NativeAutomationError);
+  });
+});

package/tests/unit/native/NativeCoordinateMapper.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import type { HTTPResponse, WaitForOptions, WaitForSelectorOptions } from 'puppeteer-core';
+import { ImageBasedCoordinateMapper } from '../../../src/native/NativeCoordinateMapper.js';
+import { CoordinateCalibrationError } from '../../../src/native/errors.js';
+import type { BrowserViewportSnapshot, NativeImageFinder, NativeImageMatch, NativeImageSearchOptions, NativeTemplateRef } from '../../../src/native/types.js';
+import type { KeyboardLike, PageLike } from '../../../src/browser/PuppeteerLike.js';
+
+class CalibrationPage implements PageLike {
+  keyboard: KeyboardLike = { type: async () => undefined, press: async () => undefined };
+  evaluates: string[] = [];
+  screenshots: Record<string, unknown>[] = [];
+  removedMarkers = 0;
+  viewport: BrowserViewportSnapshot = {
+    screenX: 0,
+    screenY: 0,
+    outerWidth: 1000,
+    outerHeight: 900,
+    innerWidth: 800,
+    innerHeight: 600,
+    devicePixelRatio: 1
+  };
+
+  async goto(_url: string, _options?: WaitForOptions): Promise<HTTPResponse | null> { return null; }
+  async waitForSelector(_selector: string, _options?: WaitForSelectorOptions): Promise<unknown> { return {}; }
+  async waitForNavigation(_options?: WaitForOptions): Promise<HTTPResponse | null> { return null; }
+  async click(_selector: string): Promise<void> {}
+  async focus(_selector: string): Promise<void> {}
+  async $eval<T>(_selector: string, _pageFunction: (element: Element, ...args: unknown[]) => T, ..._args: unknown[]): Promise<T> { throw new Error('not used'); }
+  async $$eval<T>(_selector: string, _pageFunction: (elements: Element[], ...args: unknown[]) => T, ..._args: unknown[]): Promise<T> { throw new Error('not used'); }
+  async evaluate<T>(pageFunction: (...args: unknown[]) => T, ...args: unknown[]): Promise<T> {
+    const source = pageFunction.toString();
+    this.evaluates.push(source);
+    if (source.includes('screenX')) return this.viewport as T;
+    if (args.length === 0 && source.includes('__paf_native_coordinate_markers__') && source.includes('remove')) this.removedMarkers += 1;
+    return undefined as T;
+  }
+  url(): string { return 'https://example.com'; }
+  async title(): Promise<string> { return 'Example'; }
+  async content(): Promise<string> { return '<html></html>'; }
+  async screenshot(options?: Record<string, unknown>): Promise<Uint8Array> {
+    this.screenshots.push(options ?? {});
+    return new Uint8Array([1, 2, 3]);
+  }
+}
+
+class StaticImageFinder implements NativeImageFinder {
+  constructor(private readonly matches: Record<string, NativeImageMatch>) {}
+  async findTemplate(template: string | NativeTemplateRef, _options?: NativeImageSearchOptions): Promise<NativeImageMatch | null> {
+    return this.matches[typeof template === 'string' ? template : template.name] ?? null;
+  }
+  async waitForTemplate(template: string | NativeTemplateRef, options?: NativeImageSearchOptions): Promise<NativeImageMatch> {
+    const match = await this.findTemplate(template, options);
+    if (match === null) throw new Error('missing match');
+    return match;
+  }
+}
+
+describe('ImageBasedCoordinateMapper', () => {
+  it('calibrates offset and scale from two screen marker matches', async () => {
+    const page = new CalibrationPage();
+    const mapper = new ImageBasedCoordinateMapper({
+      images: new StaticImageFinder({
+        'paf-native-calibration-a.png': { region: { x: 211, y: 321, width: 22, height: 22 } },
+        'paf-native-calibration-b.png': { region: { x: 511, y: 521, width: 22, height: 22 } }
+      })
+    });
+
+    const transform = await mapper.calibrate(page);
+
+    expect(transform.scaleX).toBe(1);
+    expect(transform.scaleY).toBe(1);
+    expect(transform.offsetX).toBe(91);
+    expect(transform.offsetY).toBe(201);
+    await expect(mapper.browserToScreen({ x: 10, y: 20 })).resolves.toEqual({ x: 101, y: 221 });
+    await expect(mapper.screenToBrowser({ x: 101, y: 221 })).resolves.toEqual({ x: 10, y: 20 });
+    expect(page.screenshots).toHaveLength(2);
+    expect(page.removedMarkers).toBe(1);
+  });
+
+  it('removes markers and rejects implausible scale values', async () => {
+    const page = new CalibrationPage();
+    const mapper = new ImageBasedCoordinateMapper({
+      images: new StaticImageFinder({
+        'paf-native-calibration-a.png': { region: { x: 0, y: 0, width: 22, height: 22 } },
+        'paf-native-calibration-b.png': { region: { x: 2000, y: 2000, width: 22, height: 22 } }
+      })
+    });
+
+    await expect(mapper.calibrate(page)).rejects.toBeInstanceOf(CoordinateCalibrationError);
+    expect(page.removedMarkers).toBe(1);
+  });
+});

package/tests/unit/native/NativeFileDialogService.test.ts

@@ -0,0 +1,91 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { DefaultNativeFileDialogService, type FileDialogAccessibilityStrategy } from '../../../src/native/NativeFileDialogService.js';
+import { NativeFileDialogError } from '../../../src/native/errors.js';
+import type { NativeKeyboard, SelectFileOptions } from '../../../src/native/types.js';
+import { FakeNativeImageFinder, FakeNativeMouse } from '../../fixtures/native/FakeNativeAutomation.js';
+
+class FakeKeyboard implements NativeKeyboard {
+  typed: string[] = [];
+  pressed: string[] = [];
+  shortcuts: Array<readonly string[]> = [];
+  async type(text: string): Promise<void> { this.typed.push(text); }
+  async pressKey(key: string): Promise<void> { this.pressed.push(key); }
+  async pressShortcut(keys: readonly string[]): Promise<void> { this.shortcuts.push([...keys]); }
+}
+
+class FakeAccessibility implements FileDialogAccessibilityStrategy {
+  calls: Array<{ filePath: string; options: SelectFileOptions }> = [];
+  constructor(private readonly error?: Error) {}
+  async selectFile(filePath: string, options: SelectFileOptions): Promise<void> {
+    this.calls.push({ filePath, options });
+    if (this.error !== undefined) throw this.error;
+  }
+}
+
+async function createTempFile(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'paf-dialog-'));
+  const filePath = path.join(dir, 'résumé "quoted".pdf');
+  await fs.writeFile(filePath, 'test');
+  return filePath;
+}
+
+describe('DefaultNativeFileDialogService', () => {
+  it('validates that the selected file exists', async () => {
+    const service = new DefaultNativeFileDialogService({ keyboard: new FakeKeyboard() });
+
+    await expect(service.selectFile('/definitely/missing/file.pdf')).rejects.toBeInstanceOf(NativeFileDialogError);
+  });
+
+  it('uses the AppleScript/accessibility strategy first in auto mode', async () => {
+    const filePath = await createTempFile();
+    const accessibility = new FakeAccessibility();
+    const keyboard = new FakeKeyboard();
+    const service = new DefaultNativeFileDialogService({ keyboard, accessibility });
+
+    await service.selectFile(filePath, { appName: 'Google Chrome' });
+
+    expect(accessibility.calls).toEqual([{ filePath, options: { appName: 'Google Chrome' } }]);
+    expect(keyboard.typed).toEqual([]);
+  });
+
+  it('falls back to keyboard selection when accessibility fails in auto mode', async () => {
+    const filePath = await createTempFile();
+    const keyboard = new FakeKeyboard();
+    const service = new DefaultNativeFileDialogService({
+      keyboard,
+      accessibility: new FakeAccessibility(new Error('permission denied'))
+    });
+
+    await service.selectFile(filePath);
+
+    expect(keyboard.shortcuts).toEqual([['Meta', 'Shift', 'G']]);
+    expect(keyboard.typed).toEqual([filePath]);
+    expect(keyboard.pressed).toEqual(['Enter', 'Enter']);
+  });
+
+  it('can click visual templates for input and open button', async () => {
+    const filePath = await createTempFile();
+    const keyboard = new FakeKeyboard();
+    const images = new FakeNativeImageFinder();
+    const mouse = new FakeNativeMouse();
+    images.matches.set('input.png', { region: { x: 10, y: 20, width: 100, height: 20 } });
+    images.matches.set('open.png', { region: { x: 200, y: 300, width: 80, height: 30 } });
+    const service = new DefaultNativeFileDialogService({ keyboard, images, mouse });
+
+    await service.selectFile(filePath, {
+      strategy: 'visual',
+      inputFieldTemplate: 'input.png',
+      openButtonTemplate: 'open.png'
+    });
+
+    expect(mouse.clicks.map(click => click.point)).toEqual([
+      { x: 60, y: 30 },
+      { x: 240, y: 315 }
+    ]);
+    expect(keyboard.typed).toEqual([filePath]);
+    expect(keyboard.pressed).toEqual(['Enter']);
+  });
+});

package/tests/unit/native/NativeMouse.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { HumanizedNativeMouse } from '../../../src/native/NativeMouse.js';
+import type { NativeMouseButton, NativePoint } from '../../../src/native/types.js';
+import type { NativeMouseDriver } from '../../../src/native/drivers.js';
+
+class FakeMouseDriver implements NativeMouseDriver {
+  position: NativePoint = { x: 0, y: 0 };
+  moves: NativePoint[] = [];
+  clicks: NativeMouseButton[] = [];
+
+  async getPosition(): Promise<NativePoint> {
+    return this.position;
+  }
+
+  async move(point: NativePoint): Promise<void> {
+    this.position = point;
+    this.moves.push(point);
+  }
+
+  async click(button: NativeMouseButton): Promise<void> {
+    this.clicks.push(button);
+  }
+}
+
+describe('HumanizedNativeMouse', () => {
+  it('moves through a ghost-cursor-style path and applies default 2-3px jitter', async () => {
+    const driver = new FakeMouseDriver();
+    const pathCalls: Array<{ from: NativePoint; to: NativePoint }> = [];
+    const mouse = new HumanizedNativeMouse(driver, {
+      coordinateMapper: { browserToScreen: async point => point },
+      random: () => 0,
+      pathGenerator: (from, to) => {
+        pathCalls.push({ from, to });
+        return [from, { x: 5, y: 5 }, to];
+      }
+    });
+
+    await mouse.moveTo({ x: 10, y: 10 });
+
+    expect(pathCalls).toEqual([{ from: { x: 0, y: 0 }, to: { x: 12, y: 10 } }]);
+    expect(driver.moves).toEqual([
+      { x: 2, y: 0 },
+      { x: 7, y: 5 },
+      { x: 12, y: 10 }
+    ]);
+  });
+
+  it('clicks by moving first, then clicking the requested button', async () => {
+    const driver = new FakeMouseDriver();
+    const mouse = new HumanizedNativeMouse(driver, {
+      coordinateMapper: { browserToScreen: async point => point },
+      random: () => 0.5,
+      pathGenerator: (_from, to) => [to]
+    });
+
+    await mouse.click({ x: 20, y: 30 }, { button: 'right', precise: true });
+
+    expect(driver.moves).toEqual([{ x: 20, y: 30 }]);
+    expect(driver.clicks).toEqual(['right']);
+  });
+
+  it('clamps jittered region clicks inside small regions', async () => {
+    const driver = new FakeMouseDriver();
+    const mouse = new HumanizedNativeMouse(driver, {
+      coordinateMapper: { browserToScreen: async point => point },
+      random: () => 0,
+      pathGenerator: (_from, to) => [to]
+    });
+
+    await mouse.clickRegion({ x: 10, y: 10, width: 2, height: 2 }, { regionPaddingPx: 0 });
+
+    const finalMove = driver.moves.at(-1);
+    expect(finalMove?.x).toBeGreaterThanOrEqual(10);
+    expect(finalMove?.x).toBeLessThanOrEqual(12);
+    expect(finalMove?.y).toBeGreaterThanOrEqual(10);
+    expect(finalMove?.y).toBeLessThanOrEqual(12);
+    expect(driver.clicks).toEqual(['left']);
+  });
+
+  it('maps browser viewport points before native clicking', async () => {
+    const driver = new FakeMouseDriver();
+    const mouse = new HumanizedNativeMouse(driver, {
+      coordinateMapper: { browserToScreen: async point => ({ x: point.x + 100, y: point.y + 200 }) },
+      pathGenerator: (_from, to) => [to]
+    });
+
+    await mouse.clickBrowserPoint({} as never, { x: 5, y: 7 }, { precise: true });
+
+    expect(driver.moves).toEqual([{ x: 105, y: 207 }]);
+  });
+});