@simular-ai/simulib-js 5.4.3

package/index.d.ts

@@ -0,0 +1,1691 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * A node in the platform accessibility tree. Thin binding for
+ * `simulib_rs::AXNode` (macOS `AXUIElement` / Windows UIA element /
+ * Linux AT-SPI accessible).
+ *
+ * Construct via the static factories or via tree-walking methods on
+ * another node / `Instance` / `Window` (`children`, `find`,
+ * `scoredSearch`). Properties are resolved from the underlying
+ * accessibility framework on each access; the node itself is just a
+ * handle.
+ */
+export declare class AccessibilityNode {
+  /** Root node of the currently focused application's accessibility tree. */
+  static fromFocusedApplication(): AccessibilityNode
+  /** Root node of the application identified by `pid`. */
+  static fromPid(pid: number): AccessibilityNode
+  /** Cross-platform ARIA role. */
+  get role(): AriaRole
+  /** Accessible name (title / label). */
+  get name(): string
+  /** Platform class name (Windows UIA `ClassName` / macOS subrole). */
+  get className(): string
+  /** Numeric control type (`UIA_ControlTypeIds` on Windows, `0` on macOS). */
+  get controlType(): number
+  /** Localized control type string. */
+  get localizedControlType(): string
+  /** Short description (`AXDescription` / UIA `Name`-adjacent fields). */
+  get description(): string
+  /**
+   * Synthetic, query-friendly description used by `scoredSearch` (combines
+   * the node's role, label, value, and a small amount of ancestor context).
+   */
+  get overallDescription(): string
+  /** Help text / tooltip. */
+  get helpText(): string
+  /** Current text value (textbox content, slider value as string, …). */
+  get value(): string
+  /** UIA `AutomationId` (Windows). Empty on macOS / Linux. */
+  get automationId(): string
+  /** Whether the node accepts user input. */
+  get isEnabled(): boolean
+  /**
+   * Live bounding box of the element in global physical pixels.
+   * `right` and `bottom` are exclusive (Playwright / DOM convention).
+   */
+  boundingBox(): BoundingBox
+  /**
+   * Direct child nodes. Returns an empty array if the subtree has been
+   * torn down or the children attribute is unreadable (matching
+   * simulib-rs's convention of treating walk failures as "no children").
+   */
+  children(): Array<AccessibilityNode>
+  /**
+   * Render this node's accessibility subtree as an indented
+   * Playwright-style aria snapshot string.
+   *
+   * One line per node, two spaces of indentation per depth level, in
+   * pre-order DFS. Roles are emitted raw (`AXWindow` on macOS,
+   * `UIA.ControlType.*` on Windows), with title and value appended when
+   * non-empty.
+   */
+  snapshot(): string
+  /**
+   * Human-readable names of the actions this node currently supports
+   * (e.g. `"activate"`, `"toggle"`, `"scroll_into_view"`).
+   */
+  supportedActions(): Array<string>
+  /**
+   * Search this subtree by *concept text*, using bag-of-words
+   * paired-Jaccard scoring against each node's `overallDescription`
+   * (`simulib_rs::AXNodeSynthetic::summary_with_context`).
+   *
+   * Returns every node whose score equals the maximum found and exceeds
+   * `threshold` — same semantics as `simulib_rs::scored_search` with
+   * `BowJaccard::score(...).primary` as the scorer and a permissive
+   * filter.
+   *
+   * - `order`               – `TraversalOrder.DepthFirst` or
+   *                           `TraversalOrder.BreadthFirst`
+   * - `max_nodes`           – upper bound on nodes visited (uses `.take()`
+   *                           over the walk)
+   * - `collapse_structural` – hoist empty structural wrappers out of the
+   *                           walk before scoring
+   * - `query`               – natural-language concept Jaccard-compared
+   *                           against each node's `overallDescription`
+   * - `threshold`           – minimum score to keep a node
+   */
+  scoredSearch(
+    order: TraversalOrder,
+    maxNodes: number,
+    collapseStructural: boolean,
+    query: string,
+    threshold: number,
+  ): Array<AccessibilityNode>
+  /** Invoke / click the element (button, link, menu item). */
+  activate(): void
+  /** Set the text value of the element (textbox, combobox, …). */
+  setValue(value: string): void
+  /** Toggle a checkbox or switch. */
+  toggle(): void
+  /** Select a tab, radio button, or list item. */
+  select(): void
+  /** Expand or collapse a dropdown or tree item. */
+  expandCollapse(): void
+  /** Scroll the element into view. */
+  scrollIntoView(): void
+  /**
+   * Move keyboard focus to this element (brings its window to the
+   * foreground as a side effect on most platforms).
+   */
+  focus(): void
+}
+
+/**
+ * Accessibility tree bound to a specific window. Provides snapshot and
+ * ref-based actions for desktop automation (Windows UIA).
+ */
+export declare class AccessibilityTree {
+  /** Create an accessibility tree bound to the current foreground window. */
+  static fromForeground(): AccessibilityTree
+  /** Create an accessibility tree bound to the first visible window of a process. */
+  static fromPid(pid: number): AccessibilityTree
+  /**
+   * Create an accessibility tree from a platform-specific window identifier.
+   * On Windows this is an HWND; on macOS it is a PID.
+   */
+  static fromHwnd(hwnd: number): AccessibilityTree
+  /** Get the window title. */
+  get windowTitle(): string
+  /** Get the window handle as an integer ID. */
+  get windowId(): number
+  /**
+   * Take a snapshot of the window's accessibility tree.
+   *
+   * `visible_only` (default `false`) controls whether nodes whose
+   * non-standard `AXVisible` attribute reads `false` are dropped from
+   * the result.
+   *
+   * `AXVisible` is a Chromium-specific extension; native macOS apps
+   * don't expose it, so the filter only matters for browser windows.
+   * Chrome reports many web-content nodes (including `AXLink`) as
+   * `AXVisible=false` because its accessibility-tree visibility is
+   * compositor-driven, not pixel-driven — setting `visible_only=true`
+   * on a Chrome window will silently drop most of the page including
+   * links.
+   */
+  snapshot(visibleOnly?: boolean | undefined | null): AccessibilityNodeJs
+  /** Invoke/click an element (button, link, menuitem). */
+  activate(refId: number): void
+  /** Set the text value of an element (textbox, combobox). */
+  setValue(refId: number, value: string): void
+  /** Toggle a checkbox or switch. */
+  toggle(refId: number): void
+  /** Select a tab, radio button, or list item. */
+  select(refId: number): void
+  /** Expand or collapse a dropdown or tree item. */
+  expandCollapse(refId: number): void
+  /** Scroll an element into view. */
+  scrollIntoView(refId: number): void
+  /** Focus an element (brings window to foreground). */
+  focusElement(refId: number): void
+  /** Get the live bounding box of an element. */
+  getBounds(refId: number): BoundingBox
+  /** Get the list of supported actions for an element. */
+  getSupportedActions(refId: number): Array<string>
+  /** Clear all stored element refs. */
+  clearRefs(): void
+  /**
+   * Search the tree using the chosen traversal order.
+   *
+   * - `order` – `TraversalOrder.DepthFirst` or `TraversalOrder.BreadthFirst`
+   * - `role`  – keep nodes whose ARIA role equals this value
+   *             (e.g. `AriaRole.Button`, `AriaRole.TabList`,
+   *             `AriaRole.MenuBar`). Cross-platform ARIA roles, not
+   *             the platform-native `UIA.ControlType.*` / `AX*` /
+   *             `AT-SPI.Role.*` vocabulary.
+   * - `name`  – keep nodes whose name contains this string
+   * - `visible_only` – skip invisible nodes (default `false`)
+   * - `max_results`  – stop after this many matches (uses `.take()`)
+   * - `collapse_structural` – hoist empty structural wrappers (for example `Pane`
+   *   / `Group` / `Custom` / `Document` on Windows, `AXGroup` /
+   *   `AXGenericGroup` / `AXUnknown` on macOS, AT-SPI `Panel` /
+   *   `Filler` / `Section` on Linux) out of the walk so role searches
+   *   do not hit unnamed containers (default `false`)
+   *
+   * Clears existing refs; returned nodes carry `refId` values usable
+   * with action methods (`activate`, `setValue`, …).
+   */
+  find(
+    order: TraversalOrder,
+    role?: AriaRole | undefined | null,
+    name?: string | undefined | null,
+    visibleOnly?: boolean | undefined | null,
+    maxResults?: number | undefined | null,
+    collapseStructural?: boolean | undefined | null,
+  ): Array<AccessibilityNodeJs>
+}
+
+/** Represents an application that can be opened. */
+export declare class App {
+  /** Get the app by exact name. No fuzzy search is performed. */
+  static exactName(name: string): App
+  /** Returns the canonical app name used for fuzzy matching. */
+  get canonicalName(): string | null
+  /** Returns the launch target used to open the app (name or path). */
+  get launchTarget(): string | null
+  /** Returns a handle to the system's default browser. */
+  static defaultBrowser(): App
+  /** Checks if the app exists. */
+  static exists(app: string): boolean
+  /**
+   * Opens or switches to an application. If a URL is provided, the URL is
+   * opened with the specified app.
+   *
+   * `focus_policy` controls whether the app is allowed to become
+   * active/frontmost. Some applications (e.g. Chrome, Notes) ignore this
+   * request and steal focus regardless.
+   *
+   * `visibility` controls whether the app is launched hidden or shown.
+   * Some applications (e.g. Chrome and other Chromium/Electron apps) ignore
+   * the hidden flag and launch visibly, potentially stealing focus. In that
+   * case the app is hidden explicitly after launch.
+   *
+   * When `wait_for_load_complete` is true, this blocks for a short, fixed
+   * delay to allow the app or URL to become responsive before returning.
+   */
+  open(
+    url: string | undefined | null,
+    focusPolicy: FocusPolicy,
+    visibility: Visibility,
+    waitForLoadComplete: boolean,
+  ): Instance
+}
+
+/**
+ * Handle to an open audio output device. Must be kept alive for
+ * playback to continue — when dropped all associated `Player`s stop
+ * producing sound.
+ */
+export declare class AudioOutput {
+  /**
+   * Opens the default audio output device with its default
+   * configuration. If that fails, tries alternative configurations
+   * and non-default output devices. Returns the first configuration
+   * that succeeds. If all attempts fail, returns the initial error.
+   */
+  static openDefault(): AudioOutput
+  /** Creates a new `Player` attached to this output. */
+  createPlayer(): Player
+}
+
+/** Contains functions to read and write the clipboard. */
+export declare class Clipboard {
+  constructor()
+  /**
+   * Gets the string content from the clipboard.
+   *
+   * Returns the clipboard string if available, or `null` if the
+   * clipboard doesn't contain string data or is empty.
+   */
+  getString(): string | null
+  /**
+   * Gets the image content from the clipboard.
+   *
+   * Returns the clipboard image if available, or `null` if the
+   * clipboard doesn't contain image data.
+   */
+  getImage(): Image | null
+  /**
+   * Replaces the contents of the clipboard with the given string.
+   *
+   * Returns the previous string content, or `null` if the clipboard
+   * was empty or had no string data. The clipboard is not
+   * automatically restored; the caller can use the returned value to
+   * restore it if desired.
+   */
+  setString(value: string): string | null
+  /**
+   * Replaces the contents of the clipboard with the given image. For
+   * example used to copy a screenshot to the clipboard.
+   *
+   * Returns the previous string content, or `null` if the clipboard
+   * was empty or had no string data. The clipboard is not
+   * automatically restored; the caller can use the returned value to
+   * restore it if desired.
+   */
+  setImage(image: Image): string | null
+  /** Clears all content from the clipboard, regardless of type. */
+  clear(): void
+  /**
+   * Types text by pasting it from the clipboard.
+   *
+   * Saves the previous clipboard text and image (when present), sets
+   * the clipboard to the specified string, verifies it was set
+   * correctly, then simulates Command+V (or Ctrl+V) to paste it.
+   * After pasting, reapplies the saved snapshot (image is restored
+   * in preference to text when both were present). Other clipboard
+   * formats are not saved or restored.
+   */
+  pasteText(value: string): void
+}
+
+/** Represents a directory handle. */
+export declare class Directory {
+  /**
+   * Creates a handle to a directory at the given path.
+   *
+   * If `create_missing` is true, the directory (and all missing
+   * ancestors) is created when it does not already exist. If false,
+   * the call fails when the directory does not exist.
+   */
+  constructor(path: string, createMissing: boolean)
+  /**
+   * Creates a directory with a unique name inside the system's temp
+   * directory, returning a handle to it. The directory is **not**
+   * automatically removed; call `delete()` when done.
+   */
+  static temp(): Directory
+  /** Returns the resolved absolute path. */
+  path(): string
+  /** Renames the directory in place (same parent directory) */
+  rename(newName: string): void
+  /** Copies the directory recursively to a new location. */
+  copyTo(dest: string): Directory
+  /**
+   * Moves the directory to a new location
+   * Falls back to copy + delete for cross-device moves.
+   */
+  moveTo(dest: string): void
+  /** Deletes the directory recursively, invalidating the handle. */
+  delete(): void
+  /**
+   * Returns all files in this directory (non-recursive).
+   *
+   * Throws if any individual directory entry fails to read.
+   */
+  listFiles(): Array<File>
+  /**
+   * Returns all subdirectories in this directory (non-recursive).
+   *
+   * Throws if any individual directory entry fails to read.
+   */
+  listDirs(): Array<Directory>
+  /** Returns the directory name (last component of the path). */
+  name(): string
+  /**
+   * Returns the last modification time of the directory itself as
+   * milliseconds since the Unix epoch.
+   */
+  modified(): number
+  /** Returns whether the directory is read-only. */
+  isReadonly(): boolean
+}
+
+/** Represents a file handle. */
+export declare class File {
+  /**
+   * Creates a handle to a file at the given path.
+   *
+   * If `create_missing` is true, the file (and all missing parent
+   * directories) is created when it does not already exist. If false,
+   * the call fails when the file does not exist.
+   */
+  constructor(path: string, createMissing: boolean)
+  /** Returns the resolved absolute path. */
+  path(): string
+  /** Reads the file and returns its trimmed contents. */
+  read(): string
+  /**
+   * Writes content to the file.
+   *
+   * When `append` is true and the file already has content, a newline is
+   * inserted before appending. When `append` is false, the file is
+   * overwritten. Parent directories are created if needed.
+   */
+  write(content: string, append: boolean): void
+  /** Renames the file in place (same parent directory). */
+  rename(newName: string): void
+  /** Copies the file to a new location, returning a handle to the copy. */
+  copyTo(dest: string): File
+  /**
+   * Moves the file to a new location.
+   * Falls back to copy + delete for cross-device moves.
+   */
+  moveTo(dest: string): void
+  /** Deletes the file, invalidating the handle. */
+  delete(): void
+  /** Returns the file name (last component of the path). */
+  name(): string
+  /** Returns the file extension, if any. */
+  extension(): string | null
+  /** Returns the file size in bytes. */
+  size(): number
+  /**
+   * Returns the last modification time as milliseconds since the Unix
+   * epoch.
+   */
+  modified(): number
+  /** Returns whether the file is read-only. */
+  isReadonly(): boolean
+}
+
+/** A visual-language grounding model that can locate concepts on images. */
+export declare class GroundingModel {
+  /**
+   * First VLM model advertised by the first VLM provider in the loaded
+   * config. Throws if no provider in the loaded config advertises a VLM
+   * service.
+   */
+  static default(): GroundingModel
+  /**
+   * Resolve a model alias against the loaded config (e.g. `"ui_venus_30b"`,
+   * `"ui_tars_7b"`, or any alias declared by a user provider). Throws if
+   * the alias is unknown.
+   */
+  static byAlias(alias: string): GroundingModel
+  /**
+   * Convenience shim for the bundled `ui_tars_7b` alias. Throws if no
+   * provider advertises that alias.
+   */
+  static uiTars7B(): GroundingModel
+  /**
+   * Convenience shim for the bundled `ui_venus_30b` alias. Throws if no
+   * provider advertises that alias.
+   */
+  static uiVenus30B(): GroundingModel
+  /**
+   * Every VLM model alias accepted by `byAlias` on this machine, deduplicated
+   * and sorted alphabetically. Use to discover what aliases the loaded config
+   * (bundled defaults plus any user provider files advertises.
+   */
+  static availableAliases(): Array<string>
+  /** The wire-level model identifier sent in the request body. */
+  get name(): string
+  /**
+   * Locate `concept` on `target` and return zero-based pixel coordinates
+   * `[x, y]`:
+   *
+   * * If `target` is an `Image`, coordinates are in **image-space**.
+   *   Normalized model outputs are scaled linearly onto
+   *   `[0, width - 1]` and `[0, height - 1]`.
+   * * If `target` is a `Screenshot`, coordinates are in **global physical
+   *   screen space** — suitable to feed directly into primitives that
+   *   expect global screen coordinates (e.g. `moveTo`, `clickAt`).
+   *
+   * Equivalent to `target.ground(model, concept)`.
+   */
+  ground(target: Image | Screenshot, concept: string): [number, number]
+}
+
+/** Represents an image. */
+export declare class Image {
+  /** Path includes the file name and the extension. */
+  save(path: string): void
+  /**
+   * Draws a cross-hair grid on the image.
+   *
+   * Grid squares have the specified `width` and `height`.
+   */
+  addGrid(width: number, height: number): void
+  /**
+   * Compress the image by converting it to JPEG with the specified quality.
+   *
+   * The quality is a value between 1 and 100.
+   * 1 is the lowest possible quality and 100 is the highest quality.
+   */
+  compress(quality: number): void
+  /**
+   * Resizes this image if it is larger than the desired size. The image's
+   * aspect ratio is preserved. The image is scaled to the maximum
+   * possible size that fits within the bounds specified by nwidth and
+   * nheight.
+   *
+   * This method operates on pixel channel values directly without taking
+   * into account color space data.
+   *
+   * We commonly use this to resize the image to 1920x1080.
+   */
+  shrink(nwidth: number, nheight: number): void
+  /** Returns the image dimensions as `[width, height]` in pixels. */
+  get dimensions(): [number, number]
+  /**
+   * Returns the image encoded as a base64 data URL.
+   *
+   * The result includes the MIME prefix, for example
+   * `data:image/png;base64,...` or `data:image/jpeg;base64,...`.
+   */
+  base64(): string
+  /**
+   * Decodes a base64 image string into an image.
+   *
+   * Accepts either a raw base64 payload or a data URL such as
+   * `data:image/png;base64,...`, `data:image/jpeg;base64,...`, or
+   * `data:image/jpg;base64,...`.
+   */
+  static fromBase64(base64: string): Image
+  /**
+   * Locate `concept` on this image using the given grounding model and
+   * return absolute zero-based pixel coordinates `[x, y]`.
+   *
+   * Equivalent to `model.ground(image, concept)`
+   */
+  ground(model: GroundingModel, concept: string): [number, number]
+}
+
+/** Represents an opened application instance. */
+export declare class Instance {
+  /** Get the process ID of the opened application (returns 0 when unknown). */
+  get pid(): number
+  /** Minimizes the instance. */
+  hide(): boolean
+  /** Shows the instance. */
+  show(): boolean
+  /** Returns true if the instance has the focus. */
+  isFocused(): boolean
+  /** Brings the instance to the foreground and gives it focus. */
+  focus(): boolean
+  content(): string
+  /** Returns true if the instance has an accessibility tree. */
+  isAccessible(): boolean
+  /**
+   * Enables the accessibility tree for the instance.
+   *
+   * This also works when the application is already running.
+   */
+  enableAccessibility(): void
+  /**
+   * Disable the accessibility tree for the instance.
+   *
+   * Creating the accessibility tree is resource-intensive, so many
+   * applications disable it by default. After we are done controlling the
+   * instance, we should disable the accessibility tree to save resources.
+   */
+  disableAccessibility(): void
+  /**
+   * Search this application's accessibility tree by *concept text*, using
+   * bag-of-words paired-Jaccard scoring against each node's
+   * `overallDescription`
+   * (`simulib_rs::AXNodeSynthetic::summary_with_context`).
+   *
+   * Mirrors `simulib_rs::Instance::scored_search` with `BowJaccard` as the
+   * scorer and a permissive filter; returns every node whose score equals
+   * the maximum found and exceeds `threshold`.
+   *
+   * - `order`               – `TraversalOrder.DepthFirst` or
+   *                           `TraversalOrder.BreadthFirst`
+   * - `max_nodes`           – upper bound on nodes visited (uses `.take()`
+   *                           over the walk)
+   * - `collapse_structural` – hoist empty structural wrappers out of the
+   *                           walk before scoring
+   * - `query`               – natural-language concept Jaccard-compared
+   *                           against each node's `overallDescription`
+   * - `threshold`           – minimum score to keep a node
+   *
+   * Returned nodes are full `AccessibilityNode` handles — call action
+   * methods (`activate`, `setValue`, …) directly on them, walk children
+   * with `.children()`, or render a snapshot with `.snapshot()`.
+   */
+  scoredSearch(
+    order: TraversalOrder,
+    maxNodes: number,
+    collapseStructural: boolean,
+    query: string,
+    threshold: number,
+  ): Array<AccessibilityNode>
+}
+
+/**
+ * Contains functions to simulate key presses/releases and to input
+ * text.
+ *
+ * For entering text, the `text` method is best. If you want to enter
+ * a key without having to worry about the layout or the keymap, use
+ * the `key` method. If you want a specific (physical) key to be
+ * pressed (e.g WASD for games), use the `raw` method. The resulting
+ * keysym will depend on the layout/keymap.
+ */
+export declare class KeyboardController {
+  constructor()
+  /**
+   * Enter the text. You can use unicode here like: ❤吅. This works regardless
+   * of the current keyboard layout. You cannot use this function for entering
+   * shortcuts or something similar. For shortcuts, use the `key` method instead.
+   */
+  text(text: string): void
+  /**
+   * Sends an individual key event. It will enter the keysym (virtual
+   * key). Have a look at the `raw` method, if you want to enter a
+   * keycode.
+   *
+   * Some of the keys are specific to a platform.
+   */
+  key(key: Key, direction: Direction): void
+  /** Sends an individual Unicode key event. Provide a single character. */
+  keyUnicode(value: string, direction: Direction): void
+  /** Sends a key event for a raw, platform-specific key value. */
+  keyOther(value: number, direction: Direction): void
+  /**
+   * Sends a raw keycode. The keycode may or may not be mapped on the
+   * current layout. You have to make sure of that yourself. This can
+   * be useful if you want to simulate a press regardless of the layout
+   * (WASD on video games). Have a look at the `key` method, if you
+   * just want to enter a specific key and don't want to worry about
+   * the layout/keymap. Windows only: If you want to enter the keycode
+   * (scancode) of an extended key, you need to set the high byte for
+   * the extended key too. You can for example do:
+   * `raw(0xE01D, Direction.Click)` to simulate `RControl`.
+   */
+  raw(keycode: number, direction: Direction): void
+}
+
+/**
+ * A loopback capture source that records system audio output (what
+ * the user hears through their speakers or headphones).
+ *
+ * Loopback capture is inherently platform-specific: macOS uses
+ * `ScreenCaptureKit` (requires screen-recording permission), Windows
+ * uses WASAPI loopback mode, and Linux uses PulseAudio/PipeWire
+ * monitor sources.
+ */
+export declare class LoopbackSource {
+  /**
+   * Opens a loopback capture stream for the given format.
+   *
+   * `channels` is the number of interleaved channels (1 = mono,
+   * 2 = stereo). `sample_rate` is samples per second per channel
+   * (e.g. 44100, 48000).
+   *
+   * The stream does not begin producing samples until `start()` is
+   * called.
+   */
+  constructor(channels: number, sampleRate: number)
+  /**
+   * Begin capturing system audio. Must be called before `record()`
+   * or `drain()`.
+   */
+  start(): void
+  /**
+   * Stop capturing. May be started again with `start()`. After
+   * stopping, call `drain()` to collect remaining buffered samples.
+   */
+  stop(): void
+  /** Number of interleaved channels (1 = mono, 2 = stereo). */
+  get channels(): number
+  /** Samples per second per channel (e.g. 44100, 48000). */
+  get sampleRate(): number
+  /**
+   * Blocks for exactly `duration_ms` and returns the captured audio as
+   * a `SamplesBuffer`. Useful for streaming fixed-size chunks while
+   * the source is still running.
+   */
+  record(durationMs: number): SamplesBuffer
+  /**
+   * Drains all buffered samples and returns them as a `SamplesBuffer`.
+   *
+   * Typical usage: call `start()`, do work while audio accumulates in
+   * the background, call `stop()`, then call `drain()` to collect
+   * everything that was captured.
+   */
+  drain(): SamplesBuffer
+}
+
+/**
+ * Contains functions to control the mouse and to get the location of
+ * the cursor. A cartesian coordinate system is used for specifying
+ * coordinates. The origin is located in the top-left corner of the
+ * current screen, with positive values extending along the axes down
+ * and to the right of the origin point and it is measured in pixels.
+ * The same coordinate system is used on all operating systems.
+ */
+export declare class MouseController {
+  constructor()
+  /**
+   * Sends an individual mouse button event. You can use this for
+   * example to simulate a click of the left mouse key. Some of the
+   * buttons are specific to a platform.
+   */
+  button(button: Button, direction: Direction): void
+  /**
+   * Move the mouse cursor to the specified x and y coordinates.
+   *
+   * You can specify absolute coordinates or relative from the current
+   * position.
+   *
+   * If you use absolute coordinates, the top left corner of your
+   * monitor screen is x=0 y=0. Move the cursor down the screen by
+   * increasing the y and to the right by increasing x coordinate.
+   *
+   * If you use relative coordinates, a positive x value moves the
+   * mouse cursor `x` pixels to the right. A negative value for `x`
+   * moves the mouse cursor to the left. A positive value of y moves
+   * the mouse cursor down, a negative one moves the mouse cursor up.
+   */
+  moveMouse(x: number, y: number, coordinate: Coordinate): void
+  /**
+   * Send a mouse scroll event.
+   *
+   * A positive length will result in scrolling down/right and negative
+   * ones up/left.
+   */
+  scroll(deltaX: number, deltaY: number): void
+  /** Get the location of the mouse in pixels. */
+  location(): [number, number]
+}
+
+/**
+ * Handle to a device that outputs sounds.
+ *
+ * Dropping the `Player` (prevent this by holding a reference) stops
+ * all its sounds.
+ */
+export declare class Player {
+  /**
+   * Decodes an audio file and appends it to the playback queue.
+   *
+   * Supports WAV, MP3, FLAC, Vorbis/OGG, and other formats
+   * depending on build features.
+   */
+  appendFile(path: string): void
+  /** Appends a sound to the queue of sounds to play. */
+  appendSamples(buffer: SamplesBuffer): void
+  /** Resumes playback of a paused player. No effect if not paused. */
+  play(): void
+  /**
+   * Pauses playback of this player.
+   *
+   * No effect if already paused. A paused player can be resumed with
+   * `play()`.
+   */
+  pause(): void
+  /** Stops the player by emptying the queue. */
+  stop(): void
+  /**
+   * Volume of the sound.
+   *
+   * The value `1.0` is the "normal" volume (unfiltered input). Any
+   * value other than `1.0` will multiply each sample by this value.
+   */
+  get volume(): number
+  /**
+   * Sets the volume of the sound.
+   *
+   * The value `1.0` is the "normal" volume (unfiltered input). Any
+   * value other than `1.0` will multiply each sample by this value.
+   */
+  set volume(value: number)
+  /**
+   * Playback speed of the sound.
+   *
+   * Increasing the speed will increase the pitch by the same factor.
+   * For example, speed `0.5` halves the frequency (lowering pitch)
+   * and speed `2` doubles it (raising pitch). Changes in speed
+   * affect the total duration inversely.
+   */
+  get speed(): number
+  /**
+   * Changes the play speed of the sound. Does not adjust the
+   * samples, only the playback speed.
+   */
+  set speed(value: number)
+  /**
+   * Whether the player is currently paused. Players can be paused
+   * and resumed using `pause()` and `play()`.
+   */
+  get isPaused(): boolean
+  /** Returns `true` if this player has no more sounds to play. */
+  empty(): boolean
+  /** Returns the number of sounds currently in the queue. */
+  len(): number
+  /** Sleeps the current thread until the sound ends. */
+  sleepUntilEnd(): void
+  /**
+   * Returns the position of the sound that's being played, in
+   * milliseconds.
+   *
+   * This takes into account any speedup or delay applied.
+   *
+   * Example: if you apply a speedup of *2* to a source and
+   * `getPos()` returns *5000* then the position in the recording
+   * is *10 seconds* from its start.
+   */
+  getPos(): number
+  /**
+   * Removes all currently loaded sources from the player and pauses
+   * it.
+   */
+  clear(): void
+  /**
+   * Skips to the next source in the player.
+   *
+   * If there are more sources appended to the player at the time,
+   * it will play the next one. Otherwise, the player will finish as
+   * if it had finished playing a source all the way through.
+   */
+  skipOne(): void
+  /**
+   * Attempts to seek to the given position (in milliseconds) in the
+   * current source.
+   *
+   * This blocks between 0 and ~5 milliseconds.
+   *
+   * As long as the duration of the source is known, seek is
+   * guaranteed to saturate at the end of the source. For example
+   * given a source that reports a total duration of 42 seconds,
+   * calling `trySeek(60000)` will seek to 42 seconds.
+   */
+  trySeek(posMs: number): void
+}
+
+/** A buffer of samples treated as a source. */
+export declare class SamplesBuffer {
+  /**
+   * Creates a new buffer from raw PCM samples.
+   *
+   * `channels` is the number of interleaved channels (1 = mono,
+   * 2 = stereo). `sample_rate` is samples per second per channel
+   * (e.g. 16000, 44100).  `samples` is an array of f32 audio
+   * samples in `[-1.0, 1.0]`.
+   */
+  constructor(channels: number, sampleRate: number, samples: Array<number>)
+  /** Number of interleaved channels (1 = mono, 2 = stereo). */
+  get channels(): number
+  /** Samples per second per channel (e.g. 16000, 44100). */
+  get sampleRate(): number
+  /** Total duration of the buffer in milliseconds. */
+  get durationMs(): number
+  /**
+   * Transcribe this audio buffer with the given speech-to-text model and
+   * return the recognized text.
+   *
+   * Equivalent to `model.transcribe(buffer)`
+   */
+  transcribe(model: SttModel): string
+}
+
+/** Represents a physical display/screen. */
+export declare class Screen {
+  /** Returns the screen identifier for the main screen. */
+  static mainScreen(): Screen
+  /**
+   * Returns the screen identifier for the screen on which the mouse
+   * is located. If the mouse is not on any screen, the main screen
+   * is returned.
+   */
+  static fromCurrentMouseLocation(): Screen
+  /**
+   * Returns the dimensions of the screen in pixels.
+   *
+   * The return value is `[x, y, width, height]`.
+   */
+  dimensions(): [number, number, number, number]
+}
+
+/** Represents a screenshot capture. */
+export declare class Screenshot {
+  /** Path includes the file name and the extension. */
+  save(path: string): void
+  /**
+   * Draws a cross-hair grid on the image.
+   *
+   * Grid squares have the specified `width` and `height`.
+   */
+  addGrid(width: number, height: number): void
+  /**
+   * Compress the image by converting it to JPEG with the specified quality.
+   *
+   * The quality is a value between 1 and 100.
+   * 1 is the lowest possible quality and 100 is the highest quality.
+   */
+  compress(quality: number): void
+  /**
+   * Resizes this image if it is larger than the desired size. The image's
+   * aspect ratio is preserved. The image is scaled to the maximum
+   * possible size that fits within the bounds specified by nwidth and
+   * nheight.
+   *
+   * This method operates on pixel channel values directly without taking
+   * into account color space data.
+   *
+   * We commonly use this to resize the image to 1920x1080.
+   */
+  shrink(nwidth: number, nheight: number): void
+  /** Returns the screenshot dimensions as `[width, height]` in pixels. */
+  get dimensions(): [number, number]
+  /**
+   * Returns the image encoded as a base64 data URL.
+   *
+   * The result includes the MIME prefix, for example
+   * `data:image/png;base64,...` or `data:image/jpeg;base64,...`.
+   */
+  base64(): string
+  /**
+   * Converts a point in this screenshot to global physical pixel
+   * coordinates.
+   *
+   * Screenshots may represent only part of a display, and displays may
+   * use different scale factors. Use this to map `(x, y)` to the
+   * corresponding global physical pixel position (for example, when
+   * moving the mouse to the same on-screen point).
+   *
+   * See `ScreenshotCoordinateType` for how `coord_type` affects
+   * interpretation of `(x, y)`.
+   */
+  toGlobalPhysicalPixels(x: number, y: number, coordType: ScreenshotCoordinateType): [number, number]
+  /**
+   * Locate `concept` on this screenshot using the given grounding model and
+   * return the corresponding **global physical pixel coordinates** `[x, y]`.
+   * The output can be fed directly to primitives that expect global screen
+   * coordinates.
+   *
+   * Equivalent to `model.ground(screenshot, concept)`.
+   */
+  ground(model: GroundingModel, concept: string): [number, number]
+}
+
+/**
+ * Describes how `(x, y)` coordinates passed to
+ * `Screenshot.toGlobalPhysicalPixels` should be interpreted.
+ */
+export declare class ScreenshotCoordinateType {
+  /**
+   * Coordinates are in screenshot image pixels (valid range:
+   * `0..=image_width-1`).
+   */
+  static absolute(): ScreenshotCoordinateType
+  /**
+   * Coordinates are normalized to a fixed range. Many VLMs (Qwen-VL,
+   * UI-TARS, etc.) output grounding coordinates in `[0, range]` rather
+   * than in pixel space. `range` specifies the inclusive upper bound
+   * (e.g. 1000, meaning valid coordinates are `0..=1000`).
+   */
+  static normalized(range: number): ScreenshotCoordinateType
+}
+
+/** A speech-to-text model that can transcribe audio. */
+export declare class SttModel {
+  /**
+   * First STT model advertised by the first STT provider in the loaded
+   * config. Throws if no provider in the loaded config advertises an STT
+   * service.
+   */
+  static default(): SttModel
+  /**
+   * Resolve a model alias against the loaded config (e.g.
+   * `"whisper_large_v3_turbo"`, `"whisper_large_v3"`, or any alias declared
+   * by a user provider). Throws if the alias is unknown.
+   */
+  static byAlias(alias: string): SttModel
+  /**
+   * Whisper Large V3 Turbo — fast, slightly less accurate. Convenience
+   * shim for the bundled `whisper_large_v3_turbo` alias.
+   */
+  static whisperLargeV3Turbo(): SttModel
+  /**
+   * Whisper Large V3 — highest accuracy. Convenience shim for the bundled
+   * `whisper_large_v3` alias.
+   */
+  static whisperLargeV3(): SttModel
+  /**
+   * Every STT model alias accepted by `byAlias` on this machine, deduplicated
+   * and sorted alphabetically. Use to discover what aliases the loaded config
+   * (bundled defaults plus any user provider files) advertises.
+   */
+  static availableAliases(): Array<string>
+  /** The wire-level model identifier sent in the request body. */
+  get name(): string
+  /** Transcribe a single audio chunk and return the recognised text. */
+  transcribe(audio: SamplesBuffer): string
+}
+
+/** Provides system-wide operations. */
+export declare class System {
+  /** Returns all available applications. */
+  static listApps(): Array<App>
+  /**
+   * Tries to find an installed app by fuzzy matching against the
+   * available app list.
+   */
+  static fuzzySearch(query: string): App
+}
+
+/**
+ * Handle to an on-screen window. Constructed via [`Window.all`] or
+ * [`Window.allForPid`] and exposes read-only metadata (`title`, `pid`)
+ * alongside basic actions (`minimize`, `maximize`, `close`).
+ */
+export declare class Window {
+  /** All visible top-level windows for a given process. */
+  static allForPid(pid: number): Array<Window>
+  /** All visible top-level windows across every process. */
+  static all(): Array<Window>
+  /** Window title (may be empty). */
+  get title(): string
+  /** Process ID that owns this window. */
+  get pid(): number
+  /** Minimize the window (hide to taskbar / Dock). */
+  minimize(): void
+  /** Maximize / zoom the window. */
+  maximize(): void
+  /**
+   * Close the window (user-equivalent to clicking the close button /
+   * pressing Alt+F4 / Cmd+W).
+   */
+  close(): void
+  /**
+   * Render the window's accessibility subtree as an indented
+   * Playwright-style aria snapshot.
+   *
+   * One line per node, two spaces of indentation per depth level, in
+   * pre-order DFS. Roles are emitted raw (`AXWindow` on macOS,
+   * `UIA.ControlType.*` on Windows), with title and value appended when
+   * non-empty. No refs are assigned — for ref-based interaction use
+   * [`AccessibilityTree.snapshot`] instead.
+   */
+  snapshot(): string
+  /**
+   * Search this window's accessibility subtree by *concept text*, using
+   * bag-of-words paired-Jaccard scoring against each node's
+   * `overallDescription`
+   * (`simulib_rs::AXNodeSynthetic::summary_with_context`).
+   *
+   * Mirrors `simulib_rs::Window::scored_search` (macOS / Linux) — on
+   * Windows we use the same underlying primitive via
+   * `WindowTrait::node().scored_search(...)`, which prebuilds the cached
+   * UIA subtree so the walk costs a single IPC. Returns every node whose
+   * score equals the maximum found and exceeds `threshold`.
+   *
+   * - `order`               – `TraversalOrder.DepthFirst` or
+   *                           `TraversalOrder.BreadthFirst`
+   * - `max_nodes`           – upper bound on nodes visited (uses `.take()`
+   *                           over the walk)
+   * - `collapse_structural` – hoist empty structural wrappers out of the
+   *                           walk before scoring
+   * - `query`               – natural-language concept Jaccard-compared
+   *                           against each node's `overallDescription`
+   * - `threshold`           – minimum score to keep a node
+   *
+   * Returned nodes are full `AccessibilityNode` handles — call action
+   * methods (`activate`, `setValue`, …) directly on them, walk children
+   * with `.children()`, or render a snapshot with `.snapshot()`.
+   */
+  scoredSearch(
+    order: TraversalOrder,
+    maxNodes: number,
+    collapseStructural: boolean,
+    query: string,
+    threshold: number,
+  ): Array<AccessibilityNode>
+}
+
+export interface AccessibilityNodeJs {
+  role: AriaRole
+  name: string
+  className: string
+  controlType: number
+  localizedControlType: string
+  description: string
+  overallDescription: string
+  helpText: string
+  value: string
+  automationId: string
+  isEnabled: boolean
+  boundingBox: BoundingBox
+  children: Array<AccessibilityNodeJs>
+  refId?: number
+}
+
+/**
+ * Cross-platform ARIA / Playwright role. Used as the `role` field on
+ * accessibility snapshots and as the search key in
+ * [`AccessibilityTree::find`].
+ */
+export declare enum AriaRole {
+  Alert = 0,
+  AlertDialog = 1,
+  Application = 2,
+  Article = 3,
+  Audio = 4,
+  Banner = 5,
+  Blockquote = 6,
+  Button = 7,
+  Caption = 8,
+  Cell = 9,
+  Checkbox = 10,
+  Code = 11,
+  ColumnHeader = 12,
+  Combobox = 13,
+  Complementary = 14,
+  ContentInfo = 15,
+  Definition = 16,
+  Deletion = 17,
+  Dialog = 18,
+  Directory = 19,
+  Document = 20,
+  Emphasis = 21,
+  Feed = 22,
+  Figure = 23,
+  Form = 24,
+  Generic = 25,
+  Grid = 26,
+  GridCell = 27,
+  Group = 28,
+  Heading = 29,
+  Img = 30,
+  Insertion = 31,
+  Link = 32,
+  List = 33,
+  ListItem = 34,
+  Listbox = 35,
+  Log = 36,
+  Main = 37,
+  Mark = 38,
+  Marquee = 39,
+  Math = 40,
+  Menu = 41,
+  MenuBar = 42,
+  MenuItem = 43,
+  MenuItemCheckbox = 44,
+  MenuItemRadio = 45,
+  Meter = 46,
+  Navigation = 47,
+  Note = 48,
+  Option = 49,
+  Paragraph = 50,
+  Password = 51,
+  Presentation = 52,
+  ProgressBar = 53,
+  Radio = 54,
+  RadioGroup = 55,
+  Region = 56,
+  Row = 57,
+  RowGroup = 58,
+  RowHeader = 59,
+  Scrollbar = 60,
+  Search = 61,
+  Searchbox = 62,
+  Separator = 63,
+  Slider = 64,
+  SpinButton = 65,
+  Status = 66,
+  Strong = 67,
+  Subscript = 68,
+  Suggestion = 69,
+  Superscript = 70,
+  Switch = 71,
+  Tab = 72,
+  Table = 73,
+  TabList = 74,
+  TabPanel = 75,
+  Term = 76,
+  Text = 77,
+  Textbox = 78,
+  Time = 79,
+  Timer = 80,
+  Toolbar = 81,
+  Tooltip = 82,
+  Tree = 83,
+  TreeItem = 84,
+  Treegrid = 85,
+  Video = 86,
+  Window = 87,
+}
+
+/**
+ * Lowercase ARIA name for a role — matches the form used in
+ * snapshot output and accepted by `AccessibilityTree.find()`.
+ *
+ * `AriaRole` is exposed to JS as a numeric enum, so the usual
+ * TypeScript reverse-mapping trick (`AriaRole[role]`) does not
+ * work; use this function instead.
+ */
+export declare function ariaRoleToString(role: AriaRole): string
+
+/**
+ * Axis-aligned rectangle. `right` and `bottom` are exclusive (Playwright /
+ * DOM convention), so the box covers `[left, right) × [top, bottom)`.
+ */
+export interface BoundingBox {
+  left: number
+  top: number
+  right: number
+  bottom: number
+}
+
+/** Represents a mouse button. */
+export declare enum Button {
+  Left = 0,
+  Middle = 1,
+  Right = 2,
+  Back = 3,
+  Forward = 4,
+  ScrollUp = 5,
+  ScrollDown = 6,
+  ScrollLeft = 7,
+  ScrollRight = 8,
+}
+
+/** Specifies if coordinates are relative or absolute. */
+export declare enum Coordinate {
+  Abs = 0,
+  Rel = 1,
+}
+
+/** The direction of a button event. */
+export declare enum Direction {
+  Press = 0,
+  Release = 1,
+  Click = 2,
+}
+
+/** Enables the accessibility tree for the frontmost application. */
+export declare function enableAccessibilityForFrontmostApp(): void
+
+/** Focus behavior when opening an application. */
+export declare enum FocusPolicy {
+  /**
+   * Request launch without forcing activation/frontmost focus; some
+   * applications may still steal focus.
+   */
+  DoNotSteal = 0,
+  /** Allow the launched app to become active/frontmost. */
+  Steal = 1,
+}
+
+export declare function hasScreenCapturePermission(): boolean
+
+/**
+ * Initialize the logger.
+ *
+ * - **No callback** (`initLogger()` or `initLogger(null, spec)`): records
+ *   are formatted as `[level] [target] message` and written to stderr.
+ * - **With a callback** (`initLogger(cb, spec)`): records are forwarded to
+ *   the JS callback via a non-blocking, unref'd threadsafe function. Use
+ *   this for GUI panels, file appenders, or routing through a logging
+ *   library like pino. The unref'd dispatch means the logger does not keep
+ *   the Node event loop alive on its own.
+ *
+ * Omit `spec` to read `RUST_LOG` (defaults to `"error"` if unset). Pass an
+ * explicit `spec` to override `RUST_LOG`. Syntax is identical to `RUST_LOG`:
+ *
+ * - `"info"` — global level
+ * - `"simulib_rs=debug,warn"` — per-module override + default
+ * - `"simulib_rs::windows=trace,simulib_rs::macos=debug,warn"` — multiple
+ * - `"off"` — disable all logging
+ *
+ * Safe to call repeatedly: each call atomically swaps the inner sink and
+ * filter — useful for e.g. starting on stderr at boot and switching to a
+ * renderer callback once the UI is ready.
+ *
+ * **Don't log from inside the callback.** Whether directly (`console.log`
+ * is fine — that's not a `log::*!` call) or transitively via another
+ * `simulib-js` function whose Rust side emits a record, you'd feed the
+ * relay another record, which queues another callback invocation, and so
+ * on forever. The callback itself runs on the Node main thread; the
+ * non-blocking dispatch from Rust is what creates the recursion risk.
+ */
+export declare function initLogger(
+  cb?: ((arg: JsLogRecord) => unknown) | undefined | null,
+  spec?: string | undefined | null,
+): void
+
+/** A single log entry forwarded to the JS callback. */
+export interface JsLogRecord {
+  /** `"error"`, `"warn"`, `"info"`, `"debug"`, or `"trace"`. */
+  level: string
+  /**
+   * Logger target — defaults to the emitting Rust module path
+   * (e.g. `"simulib_rs::windows::app"`). Used by the filter spec to gate
+   * logs per module.
+   */
+  target: string
+  /** The formatted log message. */
+  message: string
+  /** Source file path of the call site, when available. */
+  file?: string
+  /** 1-based line number of the call site, when available. */
+  line?: number
+  /** Module path of the call site, when available. */
+  modulePath?: string
+}
+
+/** Represents a keyboard key. */
+export declare enum Key {
+  Num0 = 0,
+  Num1 = 1,
+  Num2 = 2,
+  Num3 = 3,
+  Num4 = 4,
+  Num5 = 5,
+  Num6 = 6,
+  Num7 = 7,
+  Num8 = 8,
+  Num9 = 9,
+  A = 10,
+  B = 11,
+  C = 12,
+  D = 13,
+  E = 14,
+  F = 15,
+  G = 16,
+  H = 17,
+  I = 18,
+  J = 19,
+  K = 20,
+  L = 21,
+  M = 22,
+  N = 23,
+  O = 24,
+  P = 25,
+  Q = 26,
+  R = 27,
+  S = 28,
+  T = 29,
+  U = 30,
+  V = 31,
+  W = 32,
+  X = 33,
+  Y = 34,
+  Z = 35,
+  AbntC1 = 36,
+  AbntC2 = 37,
+  Accept = 38,
+  Add = 39,
+  /** alt key on Linux and Windows (option key on macOS) */
+  Alt = 40,
+  Apps = 41,
+  Attn = 42,
+  /** backspace key */
+  Backspace = 43,
+  Break = 44,
+  Begin = 45,
+  BrightnessDown = 46,
+  BrightnessUp = 47,
+  BrowserBack = 48,
+  BrowserFavorites = 49,
+  BrowserForward = 50,
+  BrowserHome = 51,
+  BrowserRefresh = 52,
+  BrowserSearch = 53,
+  BrowserStop = 54,
+  Cancel = 55,
+  /** caps lock key */
+  CapsLock = 56,
+  Clear = 57,
+  ContrastUp = 58,
+  ContrastDown = 59,
+  /** control key */
+  Control = 60,
+  Convert = 61,
+  Crsel = 62,
+  DBEAlphanumeric = 63,
+  DBECodeinput = 64,
+  DBEDetermineString = 65,
+  DBEEnterDLGConversionMode = 66,
+  DBEEnterIMEConfigMode = 67,
+  DBEEnterWordRegisterMode = 68,
+  DBEFlushString = 69,
+  DBEHiragana = 70,
+  DBEKatakana = 71,
+  DBENoCodepoint = 72,
+  DBENoRoman = 73,
+  DBERoman = 74,
+  DBESBCSChar = 75,
+  DBESChar = 76,
+  Decimal = 77,
+  /** delete key */
+  Delete = 78,
+  Divide = 79,
+  /** down arrow key */
+  DownArrow = 80,
+  Eject = 81,
+  /** end key */
+  End = 82,
+  Ereof = 83,
+  /** escape key (esc) */
+  Escape = 84,
+  Execute = 85,
+  Exsel = 86,
+  /** F1 key */
+  F1 = 87,
+  /** F2 key */
+  F2 = 88,
+  /** F3 key */
+  F3 = 89,
+  /** F4 key */
+  F4 = 90,
+  /** F5 key */
+  F5 = 91,
+  /** F6 key */
+  F6 = 92,
+  /** F7 key */
+  F7 = 93,
+  /** F8 key */
+  F8 = 94,
+  /** F9 key */
+  F9 = 95,
+  /** F10 key */
+  F10 = 96,
+  /** F11 key */
+  F11 = 97,
+  /** F12 key */
+  F12 = 98,
+  /** F13 key */
+  F13 = 99,
+  /** F14 key */
+  F14 = 100,
+  /** F15 key */
+  F15 = 101,
+  /** F16 key */
+  F16 = 102,
+  /** F17 key */
+  F17 = 103,
+  /** F18 key */
+  F18 = 104,
+  /** F19 key */
+  F19 = 105,
+  /** F20 key */
+  F20 = 106,
+  /** F21 key */
+  F21 = 107,
+  /** F22 key */
+  F22 = 108,
+  /** F23 key */
+  F23 = 109,
+  /** F24 key */
+  F24 = 110,
+  F25 = 111,
+  F26 = 112,
+  F27 = 113,
+  F28 = 114,
+  F29 = 115,
+  F30 = 116,
+  F31 = 117,
+  F32 = 118,
+  F33 = 119,
+  F34 = 120,
+  F35 = 121,
+  Function = 122,
+  Final = 123,
+  Find = 124,
+  GamepadA = 125,
+  GamepadB = 126,
+  GamepadDPadDown = 127,
+  GamepadDPadLeft = 128,
+  GamepadDPadRight = 129,
+  GamepadDPadUp = 130,
+  GamepadLeftShoulder = 131,
+  GamepadLeftThumbstickButton = 132,
+  GamepadLeftThumbstickDown = 133,
+  GamepadLeftThumbstickLeft = 134,
+  GamepadLeftThumbstickRight = 135,
+  GamepadLeftThumbstickUp = 136,
+  GamepadLeftTrigger = 137,
+  GamepadMenu = 138,
+  GamepadRightShoulder = 139,
+  GamepadRightThumbstickButton = 140,
+  GamepadRightThumbstickDown = 141,
+  GamepadRightThumbstickLeft = 142,
+  GamepadRightThumbstickRight = 143,
+  GamepadRightThumbstickUp = 144,
+  GamepadRightTrigger = 145,
+  GamepadView = 146,
+  GamepadX = 147,
+  GamepadY = 148,
+  Hangeul = 149,
+  Hangul = 150,
+  Hanja = 151,
+  Help = 152,
+  /** home key */
+  Home = 153,
+  Ico00 = 154,
+  IcoClear = 155,
+  IcoHelp = 156,
+  IlluminationDown = 157,
+  IlluminationUp = 158,
+  IlluminationToggle = 159,
+  IMEOff = 160,
+  IMEOn = 161,
+  Insert = 162,
+  Junja = 163,
+  Kana = 164,
+  Kanji = 165,
+  LaunchApp1 = 166,
+  LaunchApp2 = 167,
+  LaunchMail = 168,
+  LaunchMediaSelect = 169,
+  /** Opens launchpad */
+  Launchpad = 170,
+  LaunchPanel = 171,
+  LButton = 172,
+  LControl = 173,
+  /** left arrow key */
+  LeftArrow = 174,
+  Linefeed = 175,
+  LMenu = 176,
+  LShift = 177,
+  LWin = 178,
+  MButton = 179,
+  MediaFast = 180,
+  MediaNextTrack = 181,
+  MediaPlayPause = 182,
+  MediaPrevTrack = 183,
+  MediaRewind = 184,
+  MediaStop = 185,
+  /** meta key (also known as "windows", "super", and "command") */
+  Meta = 186,
+  /** Opens mission control */
+  MissionControl = 187,
+  ModeChange = 188,
+  Multiply = 189,
+  NavigationAccept = 190,
+  NavigationCancel = 191,
+  NavigationDown = 192,
+  NavigationLeft = 193,
+  NavigationMenu = 194,
+  NavigationRight = 195,
+  NavigationUp = 196,
+  NavigationView = 197,
+  NoName = 198,
+  NonConvert = 199,
+  None = 200,
+  /** Num lock */
+  Numlock = 201,
+  Numpad0 = 202,
+  Numpad1 = 203,
+  Numpad2 = 204,
+  Numpad3 = 205,
+  Numpad4 = 206,
+  Numpad5 = 207,
+  Numpad6 = 208,
+  Numpad7 = 209,
+  Numpad8 = 210,
+  Numpad9 = 211,
+  NumpadEnter = 212,
+  OEM1 = 213,
+  OEM102 = 214,
+  OEM2 = 215,
+  OEM3 = 216,
+  OEM4 = 217,
+  OEM5 = 218,
+  OEM6 = 219,
+  OEM7 = 220,
+  OEM8 = 221,
+  OEMAttn = 222,
+  OEMAuto = 223,
+  OEMAx = 224,
+  OEMBacktab = 225,
+  OEMClear = 226,
+  OEMComma = 227,
+  OEMCopy = 228,
+  OEMCusel = 229,
+  OEMEnlw = 230,
+  OEMFinish = 231,
+  OEMFJJisho = 232,
+  OEMFJLoya = 233,
+  OEMFJMasshou = 234,
+  OEMFJRoya = 235,
+  OEMFJTouroku = 236,
+  OEMJump = 237,
+  OEMMinus = 238,
+  OEMNECEqual = 239,
+  OEMPA1 = 240,
+  OEMPA2 = 241,
+  OEMPA3 = 242,
+  OEMPeriod = 243,
+  OEMPlus = 244,
+  OEMReset = 245,
+  OEMWsctrl = 246,
+  /** option key on macOS (alt key on Linux and Windows) */
+  Option = 247,
+  PA1 = 248,
+  Packet = 249,
+  /** page down key */
+  PageDown = 250,
+  /** page up key */
+  PageUp = 251,
+  Pause = 252,
+  Play = 253,
+  Power = 254,
+  /** Print key (e.g. print screen / `SysRq` on some keyboards) */
+  Print = 255,
+  /** Take a screenshot */
+  PrintScr = 256,
+  Processkey = 257,
+  RButton = 258,
+  RCommand = 259,
+  RControl = 260,
+  Redo = 261,
+  /** return key */
+  Return = 262,
+  /** right arrow key */
+  RightArrow = 263,
+  RMenu = 264,
+  ROption = 265,
+  RShift = 266,
+  RWin = 267,
+  Scroll = 268,
+  ScrollLock = 269,
+  Select = 270,
+  ScriptSwitch = 271,
+  Separator = 272,
+  /** shift key */
+  Shift = 273,
+  /** Lock shift key */
+  ShiftLock = 274,
+  Sleep = 275,
+  /** space key */
+  Space = 276,
+  Subtract = 277,
+  SysReq = 278,
+  /** tab key (tabulator) */
+  Tab = 279,
+  Undo = 280,
+  /** up arrow key */
+  UpArrow = 281,
+  VidMirror = 282,
+  VolumeDown = 283,
+  VolumeMute = 284,
+  VolumeUp = 285,
+  /** microphone mute toggle on linux */
+  MicMute = 286,
+  XButton1 = 287,
+  XButton2 = 288,
+  Zoom = 289,
+  /** Use `key_unicode` to provide the character. */
+  Unicode = 290,
+  /** Use `key_other` to provide the raw key value. */
+  Other = 291,
+}
+
+/** Convert a string representation into a `Key`. */
+export declare function keyFromString(value: string): Key
+
+/** Legacy helper used by Electron to open an app or URL. */
+export declare function legacyOpen(
+  app: string | undefined | null,
+  url: string | undefined | null,
+  focusPolicy: FocusPolicy,
+  visibility: Visibility,
+): void
+
+/** Legacy helper used by Electron to capture a screenshot as base64. */
+export declare function legacyTakeScreenshot(needsCompression: boolean, shrinkTo1080P: boolean): string
+
+/**
+ * Reads a file and returns its trimmed contents.
+ *
+ * If the path is relative, it is resolved against the default cache
+ * location.
+ */
+export declare function readFile(path: string): string
+
+/** Takes the screenshot of a cropped region of the workspace. */
+export declare function screenshotCropped(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  hideCursor: boolean,
+): Screenshot
+
+/** Takes the screenshot of the entire selected screen */
+export declare function screenshotFull(hideCursor: boolean, screen: Screen): Screenshot
+
+/** Tree traversal order for `AccessibilityTree.find()`. */
+export declare enum TraversalOrder {
+  /** Pre-order depth-first (each node before its descendants). */
+  DepthFirst = 0,
+  /** Level-order breadth-first (parents before children). */
+  BreadthFirst = 1,
+}
+
+/** Visibility behavior when opening an application. */
+export declare enum Visibility {
+  /** Launch hidden when supported by the platform. */
+  Hidden = 0,
+  /** Launch in a visible state. */
+  Show = 1,
+}
+
+/**
+ * Writes content to a file, returning the absolute path written to.
+ *
+ * If the path is relative, it is resolved against the default cache location.
+ * When `append` is true and the file already has content, a newline is
+ * inserted before appending the new content. When `append` is false, the file
+ * is overwritten.
+ */
+export declare function writeFile(path: string, content: string, append: boolean): string