### Common Usage Flow Example

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/modules-overview.md

Demonstrates a typical sequence of actions for automating tasks: getting the active window, navigating, interacting, verifying state, and waiting for conditions.

```text
1. Get active window or perform global search
   getActiveWindow() → Window
   screen.find(query) → Region|Point|Window

2. Navigate using movement functions
   straightTo(centerOf(region)) → Point[]
   mouse.move(path) → position cursor

3. Interact via keyboard or mouse
   keyboard.type(text) → input text
   mouse.click(Button.LEFT) → click

4. Verify state
   assert.isVisible(query) → throws on failure
   screen.find(query) → confirms presence

5. Wait for conditions
   screen.waitFor(query, timeout, interval) → element appears
```

--------------------------------

### Install nut.js

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/quick-start.md

Install the nut.js package using npm or yarn.

```bash
npm install @nut-tree/nut-js
# or
yarn add @nut-tree/nut-js
```

--------------------------------

### Install libnut with yarn

Source: https://github.com/nut-tree/nut.js/blob/develop/providers/libnut/README.md

Use this command to install the @nut-tree/libnut package using yarn.

```bash
yarn add @nut-tree/libnut
```

--------------------------------

### Install libnut with npm

Source: https://github.com/nut-tree/nut.js/blob/develop/providers/libnut/README.md

Use this command to install the @nut-tree/libnut package using npm.

```bash
npm i @nut-tree/libnut
```

--------------------------------

### Comprehensive nut.js Automation Example

Source: https://github.com/nut-tree/nut.js/blob/develop/README.md

This script demonstrates a full automation workflow using nut.js, including OCR, mouse movements, clicks, and screen searching. It requires specific addons to be installed and configured.

```javascript
"use strict";

const {
  mouse,
  screen,
  singleWord,
  sleep,
  useConsoleLogger,
  ConsoleLogLevel,
  straightTo,
  centerOf,
  Button,
  getActiveWindow,
} = require("@nut-tree/nut-js");
const {
  preloadLanguages,
  Language,
  LanguageModelType,
  configure,
} = require("@nut-tree/plugin-ocr");

configure({ languageModelType: LanguageModelType.BEST });

useConsoleLogger({ logLevel: ConsoleLogLevel.DEBUG });

screen.config.autoHighlight = true;
screen.config.ocrConfidence = 0.8;

function activeWindowRegion() {
  return getActiveWindow().then((activeWindow) => activeWindow.region);
}

(async () => {
  await preloadLanguages([Language.English], [LanguageModelType.BEST]);
  await sleep(5000);
  const result = await screen.find(singleWord("@nut-tree/nut-js"));
  await mouse.move(straightTo(centerOf(result)));
  await mouse.click(Button.LEFT);
  await screen.waitFor(singleWord("Native"), 15000, 1000, {
    providerData: { partialMatch: true },
  });
  const content = await screen.read({ searchRegion: activeWindowRegion() });
  console.log(content);
})();

```

--------------------------------

### Install libxtst-dev on Ubuntu

Source: https://github.com/nut-tree/nut.js/blob/develop/README.md

On *buntu distributions, the libXtst library is required for nut.js. Install it using apt-get.

```bash
sudo apt-get install libxtst-dev
```

--------------------------------

### Install Snapshot Release with npm

Source: https://github.com/nut-tree/nut.js/blob/develop/README.md

Install the most recent development release of nut.js using npm to test upcoming features.

```bash
npm i @nut-tree/nut-js@next
```

--------------------------------

### Install nut.js with npm

Source: https://github.com/nut-tree/nut.js/blob/develop/README.md

Install nut.js and its dependencies using npm. This command is used after subscribing to a plan and setting up registry access.

```bash
npm i @nut-tree/nut-js
```

--------------------------------

### Install TypeScript and ts-node

Source: https://github.com/nut-tree/nut.js/blob/develop/examples/typescript-test/README.md

Install the necessary TypeScript tools for your project.

```shell
npm i typescript ts-node
```

--------------------------------

### Basic Script Setup

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/quick-start.md

Import necessary modules and set up an async main function for your automation script.

```typescript
import {
  keyboard,
  mouse,
  screen,
  sleep,
  centerOf,
  straightTo,
  singleWord,
  getActiveWindow
} from "@nut-tree/nut-js";

async function main() {
  try {
    // Your automation code here
  } catch (error) {
    console.error("Automation failed:", error.message);
  }
}

main();
```

--------------------------------

### Install Snapshot Release with yarn

Source: https://github.com/nut-tree/nut.js/blob/develop/README.md

Install the most recent development release of nut.js using yarn to test upcoming features.

```bash
yarn add @nut-tree/nut-js@next
```

--------------------------------

### Example Custom Logger Implementation

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/logging.md

An example demonstrating how to create and register a custom logger using console methods. This shows a basic implementation of the LogProviderInterface.

```typescript
import { useLogger } from "@nut-tree/nut-js";

const customLogger = {
  debug: (msg, extra) => console.log("[DEBUG]", msg, extra),
  info: (msg, extra) => console.log("[INFO]", msg, extra),
  warn: (msg, extra) => console.warn("[WARN]", msg, extra),
  error: (msg, extra) => console.error("[ERROR]", msg, extra),
  trace: (msg, extra) => console.log("[TRACE]", msg, extra)
};

useLogger(customLogger);
```

--------------------------------

### Install nut.js with yarn

Source: https://github.com/nut-tree/nut.js/blob/develop/README.md

Install nut.js and its dependencies using yarn. This command is used after subscribing to a plan and setting up registry access.

```bash
yarn add @nut-tree/nut-js
```

--------------------------------

### Install macOS Command Line Tools

Source: https://github.com/nut-tree/nut.js/blob/develop/README.md

On macOS, Xcode command line tools are required. Install them by running this command in your terminal.

```bash
xcode-select --install
```

--------------------------------

### Create WindowQuery

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Examples of creating `WindowQuery` instances using a string title and a regular expression.

```typescript
import { windowWithTitle } from "@nut-tree/nut-js";
const query = windowWithTitle("My App");
const regexQuery = windowWithTitle(/Chrome.*Version/);
```

--------------------------------

### EasingFunction Examples

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Provides examples of different easing functions, including linear, ease-in, and ease-out.

```typescript
const linear: EasingFunction = (_: number): number => 0;
const easeIn: EasingFunction = (t: number): number => t * t;
const easeOut: EasingFunction = (t: number): number => t * (2 - t);
```

--------------------------------

### Create WordQuery

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Example of creating a `WordQuery` to search for the word 'Search'.

```typescript
import { singleWord } from "@nut-tree/nut-js";
const query = singleWord("Search");
```

--------------------------------

### Method Chaining Example

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/modules-overview.md

Demonstrates fluent API patterns using method chaining for keyboard and mouse operations. This allows for sequential command execution.

```typescript
await keyboard.type("text").then(() => keyboard.pressKey(Key.Enter));
await mouse.setPosition(point).then(() => mouse.leftClick());
```

--------------------------------

### Verify Clipboard Content After Setting

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/clipboard.md

This example shows how to set clipboard content and then immediately verify that the content was set correctly by retrieving it.

```typescript
import { clipboard } from "@nut-tree/nut-js";

// Set content
await clipboard.setContent("test");

// Verify it was set
const content = await clipboard.getContent();
console.log(content === "test"); // true
```

--------------------------------

### Create LineQuery

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Example of creating a `LineQuery` to search for the text 'Full line of text'.

```typescript
import { textLine } from "@nut-tree/nut-js";
const query = textLine("Full line of text");
```

--------------------------------

### Create ColorQuery

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Example of creating a `ColorQuery` to search for red pixels (RGBA(255, 0, 0, 255)).

```typescript
import { pixelWithColor, RGBA } from "@nut-tree/nut-js";
const query = pixelWithColor(new RGBA(255, 0, 0, 255));
```

--------------------------------

### Press and Release Keys with nut.js

Source: https://github.com/nut-tree/nut.js/blob/develop/examples/keyboard-test/README.md

Use `pressKey` to hold keys and `releaseKey` to release them. This example demonstrates pressing and releasing Alt+F4.

```javascript
const {keyboard, Key} = require("@nut-tree/nut-js");

describe("Keyboard test", () => {
    it("should press and release Alt+F4", async () => {
        await keyboard.pressKey(Key.LeftAlt, Key.F4);
        await keyboard.releaseKey(Key.LeftAlt, Key.F4);
    });
});
```

--------------------------------

### Mouse Button Usage

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Example of how to use the Button enum to perform a mouse click.

```typescript
import { mouse, Button } from "@nut-tree/nut-js";
await mouse.click(Button.LEFT);
```

--------------------------------

### Setup Jest Matchers

Source: https://github.com/nut-tree/nut.js/blob/develop/examples/jest-test/README.md

Extend Jest's expect with nut.js custom matchers to enable UI testing capabilities.

```javascript
const {jestMatchers} = require("@nut-tree/nut-js");

expect.extend(jestMatchers);
```

--------------------------------

### Jest Integration for GUI Testing

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/quick-start.md

Example demonstrating how to use Nut.js with Jest for automating GUI tests. It includes assertions for element visibility and a full login flow simulation.

```typescript
import { screen, assert, mouse, keyboard, straightTo, centerOf, singleWord } from "@nut-tree/nut-js";
import { jestMatchers } from "@nut-tree/nut-js";

expect.extend(jestMatchers());

describe("Login", () => {
  it("should display login form", async () => {
    await assert.isVisible(singleWord("Username"));
    await assert.isVisible(singleWord("Password"));
    await assert.isVisible(singleWord("Login"));
  });

  it("should log in successfully", async () => {
    // Find and click username field
    const username = await screen.find(singleWord("Username"));
    await mouse.move(straightTo(centerOf(username)));
    await mouse.leftClick();

    // Type username
    await keyboard.type("testuser");

    // Click password field and type
    const password = await screen.find(singleWord("Password"));
    await mouse.move(straightTo(centerOf(password)));
    await mouse.leftClick();
    await keyboard.type("testpass");

    // Click login
    const loginBtn = await screen.find(singleWord("Login"));
    await mouse.move(straightTo(centerOf(loginBtn)));
    await mouse.leftClick();

    // Wait for success
    await screen.waitFor(singleWord("Welcome"), 5000, 500);
  });
});
```

--------------------------------

### Type String and Keys with nut.js

Source: https://github.com/nut-tree/nut.js/blob/develop/examples/keyboard-test/README.md

Use the `type` function to input text or key combinations. This example opens Spotlight on macOS and types 'calculator'.

```javascript
const {keyboard, Key} = require("@nut-tree/nut-js");

describe("Keyboard test", () => {
    it("should open Spotlight on macOS", async () => {
        await keyboard.type(Key.LeftSuper, Key.Space);
        await keyboard.type("calculator");
    });
});
```

--------------------------------

### Get and Focus Active Window

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Retrieves the currently active window and brings it to the foreground. Also shows how to find a window by its title and focus it.

```typescript
import { getActiveWindow, windowWithTitle } from "@nut-tree/nut-js";
import { screen } from "@nut-tree/nut-js";

// Get active window
const active = await getActiveWindow();
await active.focus();

// Get window by title
const targetWindow = await screen.find(windowWithTitle("My Application"));
await targetWindow.focus();

```

--------------------------------

### Template Resource Management: Setting Resource Directory

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/configuration.md

Configure the `resourceDirectory` for template images. This example sets the directory to a 'templates' folder relative to the project root.

```typescript
import { screen, imageResource } from "@nut-tree/nut-js";
import { resolve, join } from "path";

// Set resource directory for template images
const projectRoot = resolve(__dirname, "..");
screen.config.resourceDirectory = join(projectRoot, "templates");

// Now imageResource() loads from projectRoot/templates/
const template = await imageResource("button.png");
```

--------------------------------

### Get All Open Windows

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/core-functions.md

Fetches an array of all currently open windows on the system. Useful for enumerating available windows or finding a specific one by its properties.

```typescript
import { getWindows, windowWithTitle } from "@nut-tree/nut-js";

const windows = await getWindows();
const titles = await Promise.all(windows.map(w => w.title));
console.log("Open windows:", titles);
```

--------------------------------

### Initialize TypeScript Project

Source: https://github.com/nut-tree/nut.js/blob/develop/examples/typescript-test/README.md

Initialize a new TypeScript project with default configuration.

```shell
npx tsc --init
```

--------------------------------

### Initialize Keyboard with Provider Registry

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Shows how to instantiate a core class, KeyboardClass, by passing the ProviderRegistry instance to its constructor.

```typescript
import { KeyboardClass } from "@nut-tree/nut-js";
import providerRegistry from "@nut-tree/nut-js";

const keyboard = new KeyboardClass(providerRegistry);
```

--------------------------------

### Resize and Reposition Window

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Demonstrates how to move a window to a specific screen coordinate and resize it to a desired width and height.

```typescript
import { getActiveWindow, Point, Size } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();

// Move to position (200, 200)
await activeWindow.move(new Point(200, 200));

// Resize to 1024x768
await activeWindow.resize(new Size(1024, 768));

```

--------------------------------

### Get Window Title

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Retrieves the title of the active window. Requires the getActiveWindow function.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();
const title = await activeWindow.getTitle();
```

--------------------------------

### getColorAt()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/screen.md

Gets the RGBA color at a specific point on the screen. This is useful for pixel-level analysis or interaction.

```APIDOC
## getColorAt()

### Description
Gets the RGBA color at a specific point on the screen. This is useful for pixel-level analysis or interaction.

### Method
async

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **location** (`Point | Promise<Point>`) - Required - Screen location to sample

### Returns
`Promise<RGBA>` - Color with R, G, B, A channels

### Example
```typescript
import { screen, Point } from "@nut-tree/nut-js";

const color = await screen.getColorAt(new Point(100, 100));
console.log(`Color: ${color.toString()}`);
```
```

--------------------------------

### Quick Access by Task

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/README.md

Navigate to specific documentation sections based on the task you want to accomplish. This table maps goals to relevant API reference files and key sections.

```markdown
| Goal | Document | Key Section |
|------|----------|-------------|
| **Type text** | [keyboard.md](./api-reference/keyboard.md) | `type()` method |
| **Move mouse and click** | [mouse.md](./api-reference/mouse.md) | `move()`, `click()` |
| **Search for elements** | [screen.md](./api-reference/screen.md) | `find()`, `findAll()` |
| **Find windows** | [window.md](./api-reference/window.md) + [core-functions.md](./api-reference/core-functions.md) | `getWindows()`, `windowWithTitle()` |
| **Wait for something** | [screen.md](./api-reference/screen.md) | `waitFor()` |
| **Write tests** | [assert.md](./api-reference/assert.md) | `isVisible()`, `notVisible()` |
| **Use clipboard** | [clipboard.md](./api-reference/clipboard.md) | `setContent()`, `getContent()` |
| **Configure behavior** | [configuration.md](./configuration.md) | Config objects |
| **Handle errors** | [errors.md](./errors.md) | Error conditions |
| **See examples** | [quick-start.md](./quick-start.md) | Common workflows |
```

--------------------------------

### Get Log Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered logging provider instance from the registry. This is used for logging operations.

```typescript
public getLogProvider(): LogProviderInterface
```

--------------------------------

### Get Window Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered window provider instance from the registry. This is used for window manipulation.

```typescript
public getWindow(): WindowProviderInterface
```

--------------------------------

### Type Text and Navigate

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/INDEX.md

This pattern demonstrates typing into a field, navigating to the next field using Tab, and then typing a password.

```typescript
const field = await screen.find(singleWord("Username"));
await mouse.move(straightTo(centerOf(field)));
await mouse.leftClick();
await keyboard.type("username");
await keyboard.type(Key.Tab);
await keyboard.type("password");
```

--------------------------------

### Get Screen Height

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/screen.md

Retrieves the main screen's height in pixels, accounting for high-DPI resolutions.

```typescript
import { screen } from "@nut-tree/nut-js";

const height = screen.height();
console.log(`Screen height: ${height}px`);
```

--------------------------------

### findAll()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Searches for all GUI elements matching a description in the window. Requires a window element inspector provider.

```APIDOC
## findAll()

### Description
Searches for all GUI elements matching a description in the window. Requires a window element inspector provider.

### Method
`public async findAll`

### Parameters
#### Path Parameters
- **searchInput** (`WindowElementResultFindInput | Promise<WindowElementResultFindInput>`) - Required - Element query with description

### Returns
`Promise<WindowElement[]>` - Array of matching GUI elements

### Throws
Error if provider not available
```

--------------------------------

### Get Screen Width

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/screen.md

Retrieves the main screen's width in pixels, accounting for high-DPI resolutions.

```typescript
import { screen } from "@nut-tree/nut-js";

const width = screen.width();
console.log(`Screen width: ${width}px`);
```

--------------------------------

### Inspect Window Elements

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Demonstrates how to retrieve all GUI elements within a window or find a specific element using various criteria like type, ID, or description. Requires a provider.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const window = await getActiveWindow();

// Get all GUI elements (requires provider)
const elements = await window.getElements(100);

// Find specific element (requires provider)
const button = await window.find({
  type: "window-element",
  id: "submit-btn",
  by: { description: "Submit" }
});

```

--------------------------------

### Get Active Window Title

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Retrieves the title of the currently active window. Requires importing getActiveWindow.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();
const title = await activeWindow.title;
console.log(`Window: ${title}`);
```

--------------------------------

### Minimize and Restore Window

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Shows how to minimize a window to the taskbar and then restore it to its previous state.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const window = await getActiveWindow();

// Minimize it
await window.minimize();

// ... do something ...

// Restore it
await window.restore();

```

--------------------------------

### Instantiate MouseClass

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/mouse.md

Creates a new mouse instance using a ProviderRegistry. The constructor initializes the mouse provider with zero initial delay.

```typescript
constructor(providerRegistry: ProviderRegistry)
```

--------------------------------

### getActiveWindow

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/core-functions.md

Gets the currently active or focused window on the system. This function is useful for automating interactions with the foreground application.

```APIDOC
## getActiveWindow()

### Description
Gets the currently active/focused window.

### Method
`getActiveWindow`

### Parameters
None

### Returns
`Promise<Window>` - The active window

### Throws
Error if window operations not available

### Example
```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const active = await getActiveWindow();
const title = await active.title;
console.log(`Active window: ${title}`);
```
```

--------------------------------

### focus()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Brings the window to the foreground and gives it focus. This asynchronous operation resolves when the window is focused.

```APIDOC
## focus()

### Description
Brings the window to the foreground and gives it focus.

### Method
POST

### Endpoint
window.focus()

### Returns
`Promise<void>` - Resolves when window is focused

### Throws
Error if focus operation fails

### Example
```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();
await activeWindow.focus();
```
```

--------------------------------

### Get Active Window

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/core-functions.md

Retrieves the currently focused window on the system. Use this when you need to interact with the foreground application.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const active = await getActiveWindow();
const title = await active.title;
console.log(`Active window: ${title}`);
```

--------------------------------

### Get Color Finder Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered color finder provider instance from the registry. This is used for finding colors.

```typescript
public getColorFinder(): ColorFinderInterface
```

--------------------------------

### Screen Constructor

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/screen.md

Initializes a new Screen instance, optionally accepting find hooks for custom match callbacks.

```typescript
constructor(
  providerRegistry: ProviderRegistry,
  findHooks?: Map<FindInput, FindHookCallback[]>
)
```

--------------------------------

### Move and Click Mouse

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/mouse.md

Demonstrates moving the mouse to a specific point and then performing a left click. Can be chained with methods that return paths for more complex movements.

```typescript
import { mouse, Button, Point, centerOf } from "@nut-tree/nut-js";

// Move, then click
await mouse.move([new Point(100, 100)]);
await mouse.leftClick();

// Or chain with methods that return paths
import { straightTo } from "@nut-tree/nut-js";
const targetRegion = /* search result */;
await mouse.move(straightTo(centerOf(targetRegion)));
await mouse.leftClick();
```

--------------------------------

### Get Window Finder Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered window finder provider instance from the registry. This is used to search for windows.

```typescript
public getWindowFinder(): WindowFinderInterface
```

--------------------------------

### Get Image Writer Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered image writer provider instance from the registry. This is used for saving images.

```typescript
public getImageWriter(): ImageWriterInterface
```

--------------------------------

### Configure Runtime Settings

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/INDEX.md

Adjust configuration properties of major components like keyboard, mouse, and screen for runtime tuning.

```typescript
keyboard.config.autoDelayMs = 100;
mouse.config.mouseSpeed = 2000;
screen.config.confidence = 0.95;
```

--------------------------------

### Accessing Providers and Logging within a Core Class

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Demonstrates how a core class uses the ProviderRegistry to access specific providers (e.g., Keyboard, LogProvider) and perform actions like typing and logging.

```typescript
public async type(...input: StringOrKey): Promise<KeyboardClass> {
  // Get provider from registry
  await this.providerRegistry.getKeyboard().type(char);
  // Log via registry
  this.providerRegistry.getLogProvider().info(`Typed ${input}`);
  return this;
}
```

--------------------------------

### Get Image Reader Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered image reader provider instance from the registry. This is used for loading images.

```typescript
public getImageReader(): ImageReaderInterface
```

--------------------------------

### Get Clipboard Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered clipboard provider instance from the registry. This is used to interact with the system's clipboard.

```typescript
public getClipboard(): ClipboardProviderInterface
```

--------------------------------

### Get Screen Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered screen provider instance from the registry. This is used to interact with the system's screen.

```typescript
public getScreen(): ScreenProviderInterface
```

--------------------------------

### Registering a Custom Log Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Illustrates how to integrate a custom logger by registering it with the ProviderRegistry, ensuring all subsequent logging uses the custom implementation.

```typescript
import providerRegistry from "@nut-tree/nut-js";

// Custom logger
providerRegistry.registerLogProvider(myLogger);

// Now all instances use your logger
```

--------------------------------

### Optimize Performance Settings

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/INDEX.md

Adjust configuration settings for keyboard, mouse, and screen to potentially improve performance or responsiveness.

```typescript
keyboard.config.autoDelayMs = 50;
mouse.config.mouseSpeed = 2000;
screen.config.confidence = 0.90;
```

--------------------------------

### Get Mouse Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered mouse provider instance from the registry. This is used to interact with the system's mouse.

```typescript
public getMouse(): MouseProviderInterface
```

--------------------------------

### Get Keyboard Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered keyboard provider instance from the registry. This is used to interact with the system's keyboard.

```typescript
public getKeyboard(): KeyboardProviderInterface
```

--------------------------------

### Default Configuration Values

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/configuration.md

Shows the default configuration values for keyboard, mouse, and screen settings. These are the initial settings before any runtime modifications.

```typescript
// Keyboard defaults
keyboard.config = {
  autoDelayMs: 300
};

// Mouse defaults
mouse.config = {
  autoDelayMs: 100,
  mouseSpeed: 1000
};

// Screen defaults
screen.config = {
  confidence: 0.99,
  autoHighlight: false,
  highlightDurationMs: 500,
  highlightOpacity: 0.25,
  resourceDirectory: process.cwd()
};
```

--------------------------------

### Get Window Region

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Retrieves the position and size of the active window, clamping to screen boundaries. Requires the getActiveWindow function.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();
const region = await activeWindow.getRegion();
```

--------------------------------

### up()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/core-functions.md

Generates a straight-line path moving upwards by a specified number of pixels from the current mouse position. Useful for vertical adjustments.

```APIDOC
## up()

### Description
Generates a straight-line path moving up by the specified pixels from current position.

### Method
`up(px: number): Promise<Point[]>`

### Parameters
#### Path Parameters
- **px** (`number`) - Required - Pixels to move up

### Returns
`Promise<Point[]>` - Array of points forming upward movement

### Example
```typescript
import { mouse, up } from "@nut-tree/nut-js";

await mouse.move(up(100)); // Move up 100 pixels
```
```

--------------------------------

### getKeyboard()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieves the registered keyboard provider. This method returns the singleton instance of the keyboard provider.

```APIDOC
## getKeyboard()

### Description
Returns the registered keyboard provider.

### Method
`public getKeyboard(): KeyboardProviderInterface`

### Returns
`KeyboardProviderInterface` - Keyboard implementation

### Throws
Error if no keyboard provider is registered
```

--------------------------------

### Performance Tuning: Slow Automation for Demos

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/configuration.md

Configure high delays for slow and visible automation, suitable for demonstrations. Increase `autoDelayMs` for keyboard and mouse, and adjust `mouseSpeed`.

```typescript
// Slow, visible automation (high delays for demos)
keyboard.config.autoDelayMs = 500;
mouse.config.autoDelayMs = 200;
mouse.config.mouseSpeed = 400;
```

--------------------------------

### Get Active Window Region

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Retrieves the screen region (position and size) of the currently active window. Requires importing getActiveWindow.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();
const region = await activeWindow.region;
console.log(`Position: (${region.left}, ${region.top})`);
console.log(`Size: ${region.width}x${region.height}`);
```

--------------------------------

### Jest Integration with nut.js Matchers

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/modules-overview.md

Integrates nut.js matchers into Jest for writing assertions in tests. Ensure you have installed jest-matcher-specific packages if needed.

```typescript
expect.extend(jestMatchers());
expect(screen).toShow(singleWord("text"));
```

--------------------------------

### Core Utility Functions

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/README.md

Access core utility functions for timing, location calculation, movement building, query builders, window finders, and image I/O. Also includes logging configuration.

```APIDOC
## Core Utility Functions

### Description
Access core utility functions for timing, location calculation, movement building, query builders, window finders, and image I/O. Also includes logging configuration.

### Method
Not specified (assumed to be SDK methods)

### Endpoint
Not applicable (SDK)

### Parameters
Not specified

### Request Example
Not specified

### Response
Not specified
```

--------------------------------

### Provider Registry Architecture Diagram

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Illustrates the dependency injection pattern used by the Provider Registry, showing the flow from user application code to core classes and providers.

```text
┌─────────────────────────────────────┐
│     User Application Code           │
├─────────────────────────────────────┤
│  keyboard, mouse, screen, etc.      │
│  (public API instances)             │
├─────────────────────────────────────┤
│      ProviderRegistry               │
│  (centralized service locator)      │
├─────────────────────────────────────┤
│  Providers (implementations)         │
│  - libnut keyboard                  │
│  - libnut mouse                     │
│  - libnut screen                    │
│  - libnut clipboard                 │
│  - plugin text finder               │
│  - plugin image finder              │
│  - custom logger                    │
└─────────────────────────────────────┘
```

--------------------------------

### Handling Unavailable Text Finder Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Check for the availability of the text finder provider before attempting to use it. Install the OCR plugin if it's not available.

```typescript
if (!providerRegistry.hasTextFinder()) {
  throw new Error("Text finder provider not available. Install @nut-tree/plugin-ocr");
}

const textFinder = providerRegistry.getTextFinder();
```

--------------------------------

### Nut.js Type Guard Usage Example

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Demonstrates how to use Nut.js type guard functions to narrow down union types, such as checking if a target is a Point.

```typescript
import {
  isPoint,
  isRegion,
  isImage,
  isWordQuery,
  isLineQuery,
  isTextQuery,
  isWindowQuery,
  isColorQuery,
  isWindowElementQuery
} from "@nut-tree/nut-js";

// Usage
const target: any = /* ... */;
if (isPoint(target)) {
  console.log(target.x, target.y);
}
```

--------------------------------

### Configuration & Infrastructure

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/MANIFEST.md

Manages provider registration and logging configuration.

```APIDOC
## Provider Registry

### Description
Manages the registration and retrieval of various service providers.

### Core Methods
- **getKeyboard()**: Retrieves the keyboard provider.
- **getMouse()**: Retrieves the mouse provider.
- **getScreen()**: Retrieves the screen provider.
- **getClipboard()**: Retrieves the clipboard provider.
- **getWindow()**: Retrieves the window provider.
- **getLogProvider()**: Retrieves the logging provider.

### Reader/Writer Methods
- **getImageReader()**: Retrieves the image reader provider.
- **getImageWriter()**: Retrieves the image writer provider.

### Finder Methods
- **getWindowFinder()**: Retrieves the window finder provider.
- **getTextFinder()**: Retrieves the text finder provider.
- **getImageFinder()**: Retrieves the image finder provider.
- **getColorFinder()**: Retrieves the color finder provider.

### Element Inspection
- **getWindowElementInspector()**: Retrieves the window element inspector provider.

### Check Methods
- **hasKeyboard()**: Checks if a keyboard provider is available.
- **hasMouse()**: Checks if a mouse provider is available.
- **hasScreen()**: Checks if a screen provider is available.

### Registration Methods
- **registerLogProvider(provider: LogProvider)**: Registers a custom log provider.

## Logging

### Description
Configures and manages the logging system for the application.

### Functions
- **useConsoleLogger(config?: ConsoleLoggerConfig)**: Configures and enables the console logger with optional settings.
- **useLogger(provider: LogProvider)**: Sets a custom logger provider for the application.

### Log Levels
- **ConsoleLogLevel**: Enum defining log levels: DEBUG, INFO, WARN, ERROR.

### Integration
Supports integration with various logging scenarios, including file logging, JSON logging, filtered logging, and test framework integration.
```

--------------------------------

### Logging Configuration

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/README.md

Configure logging with console logging levels and custom logger integration.

```APIDOC
## Logging Configuration

### Description
Configure logging with console logging levels and custom logger integration.

### Method
Not specified (assumed to be SDK methods)

### Endpoint
Not applicable (SDK)

### Parameters
Not specified

### Request Example
Not specified

### Response
Not specified
```

--------------------------------

### restore()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Restores a minimized or maximized window to its normal state. Requires a window management provider. This asynchronous operation resolves when the window is restored.

```APIDOC
## restore()

### Description
Restores a minimized or maximized window to its normal state. Requires a window management provider.

### Method
POST

### Endpoint
window.restore()

### Returns
`Promise<void>` - Resolves when window is restored

### Throws
Error if provider not available or operation fails

### Example
```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();
await activeWindow.restore();
```
```

--------------------------------

### Copy Text for Pasting with Keyboard

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/clipboard.md

This snippet demonstrates copying text to the clipboard and then simulating a paste operation using keyboard shortcuts. Requires importing `clipboard`, `keyboard`, and `Key` from `@nut-tree/nut-js`.

```typescript
import { clipboard, keyboard, Key } from "@nut-tree/nut-js";

// Copy text to clipboard
await clipboard.setContent("important data");

// Paste it (Ctrl+V or Cmd+V)
await keyboard.pressKey(Key.LeftControl, Key.V);
```

--------------------------------

### Get Image Finder Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered image finder provider instance from the registry. This is used for template matching. Requires a plugin provider.

```typescript
public getImageFinder(): ImageFinderInterface
```

--------------------------------

### Handle Timeout Errors

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/errors.md

Implement error handling for operations that have a timeout. This example shows how to catch errors when an element is not found within the specified waiting period.

```typescript
import { screen, singleWord } from "@nut-tree/nut-js";

try {
  const result = await screen.waitFor(singleWord("Dialog"), 5000, 500);
} catch (error) {
  console.log("Dialog did not appear within 5 seconds");
}
```

--------------------------------

### Import ProviderRegistry Singleton

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Import the default singleton instance of the ProviderRegistry. This instance is pre-initialized with default providers.

```typescript
import providerRegistry from "@nut-tree/nut-js";
```

--------------------------------

### Handle Assertion Failed - Element Visible

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/errors.md

Verify element visibility before asserting using `assert.isVisible()`. This example shows how to first find the element and then assert its visibility.

```typescript
import { assert, singleWord } from "@nut-tree/nut-js";

// Throws error if element not visible
await assert.isVisible(singleWord("Login Button"));
```

```typescript
import { assert, singleWord, screen } from "@nut-tree/nut-js";

// First verify it exists
try {
  const element = await screen.find(singleWord("Login Button"));
  // Then assert
  await assert.isVisible(singleWord("Login Button"));
} catch (e) {
  console.log("Element not found:", e.message);
}
```

--------------------------------

### getWindows

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/core-functions.md

Retrieves a list of all currently open windows on the system. This can be used to enumerate available applications or to find specific windows by their properties.

```APIDOC
## getWindows()

### Description
Gets all open windows on the system.

### Method
`getWindows`

### Parameters
None

### Returns
`Promise<Window[]>` - Array of all open windows

### Throws
Error if window operations not available

### Example
```typescript
import { getWindows, windowWithTitle } from "@nut-tree/nut-js";

const windows = await getWindows();
const titles = await Promise.all(windows.map(w => w.title));
console.log("Open windows:", titles);
```
```

--------------------------------

### Window Management

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/README.md

Manage windows by querying and controlling their properties such as position, size, focus, and minimize/restore state. Allows for GUI element inspection.

```APIDOC
## Window Management

### Description
Manage windows by querying and controlling their properties such as position, size, focus, and minimize/restore state. Allows for GUI element inspection.

### Method
Not specified (assumed to be SDK methods)

### Endpoint
Not applicable (SDK)

### Parameters
Not specified

### Request Example
Not specified

### Response
Not specified
```

--------------------------------

### Get Current Mouse Position

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/mouse.md

Retrieves the current coordinates of the mouse cursor as a Point object. The returned Promise resolves with an object containing x and y coordinates.

```typescript
import { mouse } from "@nut-tree/nut-js";

const currentPos = await mouse.getPosition();
console.log(`Mouse at ${currentPos.x}, ${currentPos.y}`);
```

--------------------------------

### Get Color at Specific Screen Point

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/screen.md

Retrieves the RGBA color of a pixel at a given screen coordinate. Useful for pixel-perfect checks or dynamic UI analysis.

```typescript
import { screen, Point } from "@nut-tree/nut-js";

const color = await screen.getColorAt(new Point(100, 100));
console.log(`Color: ${color.toString()}`);
```

--------------------------------

### Screen Configuration Interface

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/screen.md

Defines the configuration options for screen searching and highlighting, including confidence levels and visual feedback.

```typescript
interface ScreenConfig {
  confidence: number;              // Default: 0.99
  autoHighlight: boolean;          // Default: false
  highlightDurationMs: number;     // Default: 500
  highlightOpacity: number;        // Default: 0.25
  resourceDirectory: string;       // Default: current working directory
}
```

--------------------------------

### Get Window Elements

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/window.md

Retrieves the accessibility tree of GUI elements within the active window. Requires a window element inspector provider and the getActiveWindow function.

```typescript
import { getActiveWindow } from "@nut-tree/nut-js";

const activeWindow = await getActiveWindow();
const elements = await activeWindow.getElements();
console.log(elements);
```

--------------------------------

### Write a Simple nut.js TypeScript Test

Source: https://github.com/nut-tree/nut.js/blob/develop/examples/typescript-test/README.md

A basic TypeScript test using nut.js to highlight a screen region.

```typescript
import { Region, screen } from "@nut-tree/nut-js";

(async () => {
	await screen.highlight(new Region(100, 200, 300, 400));
})();
```

--------------------------------

### Get Window Element Inspector Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered element inspector provider instance from the registry. This is used for inspecting window elements. Requires a plugin provider.

```typescript
public getWindowElementInspector(): ElementInspectionProviderInterface
```

--------------------------------

### Get Text Finder Provider

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieve the registered text finder provider instance from the registry. This is used for Optical Character Recognition (OCR). Requires a plugin provider.

```typescript
public getTextFinder(): TextFinderInterface
```

--------------------------------

### Performance Tuning: Fast Automation

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/configuration.md

Configure low delays for fast and efficient automation. Adjust `autoDelayMs` for keyboard and mouse, and `mouseSpeed` for quicker mouse movements.

```typescript
import { keyboard, mouse, screen } from "@nut-tree/nut-js";

// Fast, efficient automation (low delays)
keyboard.config.autoDelayMs = 50;
mouse.config.autoDelayMs = 50;
mouse.config.mouseSpeed = 2000;
```

--------------------------------

### Copy Text to Clipboard

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/clipboard.md

Use `setContent` to copy a string to the system clipboard. Ensure the `@nut-tree/nut-js` library is imported.

```typescript
import { clipboard } from "@nut-tree/nut-js";

await clipboard.setContent("Hello, clipboard!");
console.log("Text copied to clipboard");
```

--------------------------------

### Handle Invalid Image Channels

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/errors.md

When creating an `Image` object, ensure the number of channels is valid (typically 3 for RGB/BGR or 4 for RGBA/BGRA). This example shows creating a valid image.

```typescript
import { Image } from "@nut-tree/nut-js";

// Throws error - 0 channels invalid
new Image(100, 100, Buffer.from([]), 0, "id", 32, 400);
```

```typescript
import { Image } from "@nut-tree/nut-js";

const img = new Image(100, 100, Buffer.from([]), 4, "id", 32, 400); // Valid
```

--------------------------------

### Nut.js Documentation Structure Overview

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/README.md

This tree represents the file structure of the Nut.js documentation. It helps in understanding where to find specific information within the project.

```tree
output/
├── INDEX.md                    # Master index and navigation
├── README.md                   # This file
├── quick-start.md              # Getting started and common patterns
├── modules-overview.md         # Architecture and design
├── types.md                    # Type reference
├── configuration.md            # Configuration options
├── errors.md                   # Error reference
└── api-reference/
    ├── keyboard.md             # KeyboardClass API
    ├── mouse.md                # MouseClass API
    ├── screen.md               # ScreenClass API
    ├── window.md               # Window class API
    ├── clipboard.md            # ClipboardClass API
    ├── assert.md               # AssertClass API
    ├── core-functions.md       # Standalone functions
    ├── provider-registry.md    # ProviderRegistry API
    └── logging.md              # Logging configuration
```

--------------------------------

### Filtered Logging with Custom Logger

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/logging.md

Create a custom logger that selectively logs messages based on certain criteria, such as message content or log level. Trace logs are explicitly skipped in this example.

```typescript
import { useLogger } from "@nut-tree/nut-js";

const filteredLogger = {
  debug: (msg, extra) => {
    if (msg.includes("important")) {
      console.log("[DEBUG]", msg);
    }
  },
  info: (msg, extra) => console.log("[INFO]", msg),
  warn: (msg, extra) => console.warn("[WARN]", msg),
  error: (msg, extra) => console.error("[ERROR]", msg),
  trace: (msg, extra) => {
    // Skip trace logs
  }
};

useLogger(filteredLogger);
```

--------------------------------

### pressKey()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/keyboard.md

Presses and holds a key combination. Modifiers should be provided first, followed by the main key. Returns the keyboard instance for method chaining.

```APIDOC
## pressKey()

### Description
Presses and holds a key combination. Modifiers should be provided first, followed by the main key. Returns the keyboard instance for method chaining.

### Method
`public async pressKey(...keys: Key[]): Promise<KeyboardClass>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { keyboard, Key } from "@nut-tree/nut-js";

// Press Ctrl+V (paste)
await keyboard.pressKey(Key.LeftControl, Key.V);

// Press Shift+A
await keyboard.pressKey(Key.LeftShift, Key.A);
```

### Response
#### Success Response
`Promise<KeyboardClass>` for chaining

#### Response Example
None explicitly defined, returns the keyboard instance for chaining.

### Throws
Error if key combination cannot be pressed
```

--------------------------------

### Get Random Point in Region with randomPointIn()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/core-functions.md

Use randomPointIn to generate a random point within the boundaries of a specified region. This can be helpful for simulating more natural user interactions or avoiding fixed click locations.

```typescript
import { screen, randomPointIn, singleWord, mouse } from "@nut-tree/nut-js";

// Move to random location within found element
const element = await screen.find(singleWord("Area"));
const randomLoc = await randomPointIn(element);
await mouse.move(randomLoc);
```

--------------------------------

### Image

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/types.md

Represents image pixel data with properties like `width`, `height`, `data`, `channels`, `id`, `bitsPerPixel`, `byteWidth`, `colorMode`, and `pixelDensity`. It includes methods `get hasAlphaChannel`, `toRGB()`, `toBGR()`, and a static method `fromRGBData()`.

```APIDOC
## Class: Image

### Description
Represents image pixel data.

### Fields
- **width** (`number`) - Image width in pixels
- **height** (`number`) - Image height in pixels
- **data** (`Buffer`) - Raw pixel data
- **channels** (`number`) - Color channels (3 or 4)
- **id** (`string`) - Unique image identifier
- **bitsPerPixel** (`number`) - Bits per pixel (usually 24 or 32)
- **byteWidth** (`number`) - Bytes per image row
- **colorMode** (`ColorMode`) - Color format (BGR or RGB)
- **pixelDensity** (`{ scaleX: number; scaleY: number }`) - DPI scale factors

### Methods
- `get hasAlphaChannel`: Returns boolean indicating if the image has an alpha channel.
- `toRGB()`: Returns a Promise resolving to an Image in RGB format.
- `toBGR()`: Returns a Promise resolving to an Image in BGR format.
- `static fromRGBData(...)`: Static method to create an Image from RGB data.
```

--------------------------------

### Screen & Window API

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/MANIFEST.md

Interact with the screen to find elements, capture screenshots, and manage windows.

```APIDOC
## Screen API

### Description
Provides methods for screen interaction, including finding elements, capturing screenshots, and reading text.

### Methods
- **constructor(config?: ScreenConfig)**: Initializes the Screen class.
- **width()**: Gets the screen width.
- **height()**: Gets the screen height.
- **find(image: Image | string, options?: FindOptions)**: Finds the first occurrence of an image on the screen.
- **findAll(image: Image | string, options?: FindAllOptions)**: Finds all occurrences of an image on the screen.
- **waitFor(image: Image | string, options?: WaitForOptions)**: Waits for the first occurrence of an image.
- **waitForAll(image: Image | string, options?: WaitForAllOptions)**: Waits for all occurrences of an image.
- **getColorAt(x: number, y: number, options?: ColorAtOptions)**: Gets the color of a pixel at the specified coordinates.
- **screenshot(path?: string, options?: ScreenshotOptions)**: Captures a screenshot of the screen.
- **highlight(region: Region, options?: HighlightOptions)**: Visually highlights a specified region on the screen.
- **read(region?: Region, options?: ReadOptions)**: Reads text from a specified region using OCR.

## Window API

### Description
Provides methods for interacting with and managing application windows.

### Methods
- **constructor(options?: WindowOptions)**: Initializes the Window class.
- **getTitle()**: Gets the title of the window.
- **getRegion()**: Gets the region of the window.
- **move(x: number, y: number, options?: MoveOptions)**: Repositions the window.
- **resize(width: number, height: number, options?: ResizeOptions)**: Resizes the window.
- **focus()**: Activates and brings the window to the foreground.
- **minimize()**: Minimizes the window.
- **restore()**: Restores a minimized window.
- **getElements(options?: GetElementsOptions)**: Retrieves the GUI tree of elements within the window.
- **find(selector: string, options?: FindElementOptions)**: Finds a specific GUI element within the window.
- **findAll(selector: string, options?: FindAllElementsOptions)**: Finds all GUI elements matching the selector.
- **waitForElement(selector: string, options?: WaitForElementOptions)**: Waits for a specific GUI element to appear.
```

--------------------------------

### Custom mouse movement with easing function

Source: https://github.com/nut-tree/nut.js/blob/develop/examples/mouse-test/README.md

Customize mouse movement speed along a path using an easing function. This example demonstrates a function that makes the cursor move slower initially and then faster. Requires importing `left`.

```javascript
const firstSlowThenFast = (percentage) => {
	return percentage <= 0.5 ? -0.75 : 0.75;
}

await mouse.move(left(1000), firstSlowThenFast);
```

--------------------------------

### Method chaining for keyboard actions

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/keyboard.md

Chaining multiple keyboard actions allows for sequential execution of commands, such as selecting all text and then copying it.

```typescript
import { keyboard, Key } from "@nut-tree/nut-js";

await keyboard
  .type(Key.LeftControl, Key.A)  // Select all
  .then(() => keyboard.type(Key.LeftControl, Key.C));  // Copy
```

--------------------------------

### getScreen()

Source: https://github.com/nut-tree/nut.js/blob/develop/_autodocs/api-reference/provider-registry.md

Retrieves the registered screen provider. This method returns the singleton instance of the screen provider.

```APIDOC
## getScreen()

### Description
Returns the registered screen provider.

### Method
`public getScreen(): ScreenProviderInterface`

### Returns
`ScreenProviderInterface` - Screen implementation

### Throws
Error if no screen provider is registered
```