@epsilon-asi/actors 0.0.21 → 0.0.32

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(', ');
+}

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;
+  }
+}