@epsilon-asi/actors 0.0.21 → 0.0.32

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

package/src/native/nut/NutNativeKeyboardDriver.ts

@@ -0,0 +1,38 @@
+import type { NativeKeyboardDriver } from '../drivers.js';
+import { loadNut } from './loadNut.js';
+
+function keyName(key: string): string {
+  const normalized = key.toLowerCase();
+  if (normalized === 'enter' || normalized === 'return') return 'ENTER';
+  if (normalized === 'escape' || normalized === 'esc') return 'ESCAPE';
+  if (normalized === 'meta' || normalized === 'command' || normalized === 'cmd') return 'LEFT_META';
+  if (normalized === 'control' || normalized === 'ctrl') return 'LEFT_CONTROL';
+  if (normalized === 'shift') return 'LEFT_SHIFT';
+  if (normalized === 'alt' || normalized === 'option') return 'LEFT_ALT';
+  return key.toUpperCase();
+}
+
+export class NutNativeKeyboardDriver implements NativeKeyboardDriver {
+  async type(text: string): Promise<void> {
+    const nut = await loadNut();
+    await nut.keyboard.type(text);
+  }
+
+  async pressKey(key: string): Promise<void> {
+    const nut = await loadNut();
+    await nut.keyboard.pressKey(this.resolveKey(nut.Key, key));
+  }
+
+  async pressShortcut(keys: readonly string[]): Promise<void> {
+    const nut = await loadNut();
+    const resolved = keys.map(key => this.resolveKey(nut.Key, key));
+    await nut.keyboard.pressKey(...resolved);
+    if (nut.keyboard.releaseKey !== undefined) {
+      await nut.keyboard.releaseKey(...resolved.slice().reverse());
+    }
+  }
+
+  private resolveKey(keyMap: Record<string, unknown> | undefined, key: string): unknown {
+    return keyMap?.[keyName(key)] ?? key;
+  }
+}

package/src/native/nut/NutNativeMouseDriver.ts

@@ -0,0 +1,27 @@
+import type { NativeMouseDriver } from '../drivers.js';
+import type { NativeMouseButton, NativePoint } from '../types.js';
+import { loadNut } from './loadNut.js';
+
+function buttonName(button: NativeMouseButton): string {
+  if (button === 'left') return 'LEFT';
+  if (button === 'right') return 'RIGHT';
+  return 'MIDDLE';
+}
+
+export class NutNativeMouseDriver implements NativeMouseDriver {
+  async getPosition(): Promise<NativePoint> {
+    const nut = await loadNut();
+    return nut.mouse.getPosition();
+  }
+
+  async move(point: NativePoint): Promise<void> {
+    const nut = await loadNut();
+    await nut.mouse.move(nut.straightTo({ x: point.x, y: point.y }));
+  }
+
+  async click(button: NativeMouseButton): Promise<void> {
+    const nut = await loadNut();
+    const nutButton = nut.Button?.[buttonName(button)] ?? button;
+    await nut.mouse.click(nutButton);
+  }
+}

package/src/native/nut/NutNativeScreenDriver.ts

@@ -0,0 +1,14 @@
+import type { NativeScreenDriver } from '../drivers.js';
+import { loadNut } from './loadNut.js';
+
+export class NutNativeScreenDriver implements NativeScreenDriver {
+  async width(): Promise<number> {
+    const nut = await loadNut();
+    return nut.screen.width();
+  }
+
+  async height(): Promise<number> {
+    const nut = await loadNut();
+    return nut.screen.height();
+  }
+}

package/src/native/nut/NutNativeWindowDriver.ts

@@ -0,0 +1,61 @@
+import type { NativeWindowDriver, NativeWindowHandle } from '../drivers.js';
+import type { NativePoint, NativeRegion, NativeSize, NativeWindowInfo } from '../types.js';
+import { loadNut, type NutRegion, type NutWindow } from './loadNut.js';
+
+function toRegion(region: NutRegion): NativeRegion {
+  return {
+    x: region.left ?? region.x ?? 0,
+    y: region.top ?? region.y ?? 0,
+    width: region.width,
+    height: region.height
+  };
+}
+
+class NutNativeWindowHandle implements NativeWindowHandle {
+  constructor(private readonly window: NutWindow) {}
+
+  async info(): Promise<NativeWindowInfo> {
+    const [title, region] = await Promise.all([
+      Promise.resolve(this.window.title),
+      Promise.resolve(this.window.region)
+    ]);
+    return {
+      title,
+      region: toRegion(region)
+    };
+  }
+
+  async focus(): Promise<void> {
+    await this.window.focus();
+  }
+
+  async minimize(): Promise<void> {
+    await this.window.minimize();
+  }
+
+  async restore(): Promise<void> {
+    await this.window.restore();
+  }
+
+  async move(point: NativePoint): Promise<void> {
+    await this.window.move({ x: point.x, y: point.y });
+  }
+
+  async resize(size: NativeSize): Promise<void> {
+    await this.window.resize(size);
+  }
+}
+
+export class NutNativeWindowDriver implements NativeWindowDriver {
+  async list(): Promise<NativeWindowHandle[]> {
+    const nut = await loadNut();
+    const windows = await nut.getWindows();
+    return windows.map(window => new NutNativeWindowHandle(window));
+  }
+
+  async active(): Promise<NativeWindowHandle | null> {
+    const nut = await loadNut();
+    const window = await nut.getActiveWindow();
+    return new NutNativeWindowHandle(window);
+  }
+}

package/src/native/nut/loadNut.ts

@@ -0,0 +1,86 @@
+import { NativeDependencyError } from '../errors.js';
+
+type DynamicImport = (specifier: string) => Promise<unknown>;
+
+const dynamicImport = new Function('specifier', 'return import(specifier)') as DynamicImport;
+
+export interface NutPoint {
+  x: number;
+  y: number;
+}
+
+export interface NutRegion {
+  left?: number;
+  top?: number;
+  x?: number;
+  y?: number;
+  width: number;
+  height: number;
+}
+
+export interface NutWindow {
+  title: Promise<string> | string;
+  region: Promise<NutRegion> | NutRegion;
+  focus(): Promise<void>;
+  minimize(): Promise<void>;
+  restore(): Promise<void>;
+  move(point: NutPoint): Promise<void>;
+  resize(size: { width: number; height: number }): Promise<void>;
+}
+
+export interface NutModule {
+  mouse: {
+    getPosition(): Promise<NutPoint>;
+    move(path: unknown): Promise<void>;
+    click(button: unknown): Promise<void>;
+  };
+  keyboard: {
+    type(text: string): Promise<void>;
+    pressKey(...keys: unknown[]): Promise<void>;
+    releaseKey?(...keys: unknown[]): Promise<void>;
+  };
+  screen: {
+    width(): Promise<number>;
+    height(): Promise<number>;
+    find?(resource: unknown, options?: unknown): Promise<NutRegion>;
+    waitFor?(resource: unknown, timeoutMs?: number, intervalMs?: number): Promise<NutRegion>;
+    config?: {
+      confidence?: number;
+      resourceDirectory?: string;
+    };
+  };
+  getWindows(): Promise<NutWindow[]>;
+  getActiveWindow(): Promise<NutWindow>;
+  straightTo(point: NutPoint): unknown;
+  imageResource?(path: string): unknown;
+  Button?: Record<string, unknown>;
+  Key?: Record<string, unknown>;
+}
+
+export interface NlMatcherModule {
+  useNlMatcher(): void;
+}
+
+let nutModulePromise: Promise<NutModule> | null = null;
+let nlMatcherLoaded = false;
+
+export async function loadNut(): Promise<NutModule> {
+  nutModulePromise ??= dynamicImport('@nut-tree/nut-js')
+    .then(module => module as NutModule)
+    .catch(error => {
+      nutModulePromise = null;
+      throw new NativeDependencyError('@nut-tree/nut-js', error);
+    });
+  return nutModulePromise;
+}
+
+export async function loadNlMatcher(): Promise<void> {
+  if (nlMatcherLoaded) return;
+  const module = await dynamicImport('@nut-tree/nl-matcher')
+    .then(value => value as NlMatcherModule)
+    .catch(error => {
+      throw new NativeDependencyError('@nut-tree/nl-matcher', error);
+    });
+  module.useNlMatcher();
+  nlMatcherLoaded = true;
+}