> ## Documentation Index > Fetch the complete documentation index at: https://docs.simular.ai/llms.txt > Use this file to discover all available pages before exploring further. # Index # `@simular-ai/simulang-js` ![CI](https://github.com/simular-ai/simulang-js/workflows/CI/badge.svg) Node.js bindings for [`simulang-rs`](https://github.com/simular-ai/simulang-rs), a Rust crate published by [Simular](https://simular.ai), built with [`napi-rs`](https://napi.rs/). Provides high-level primitives for desktop automation — keyboard and mouse input, screenshots, clipboard access, audio capture, accessibility-tree inspection, and more — exposed through idiomatic JavaScript. Ships TypeScript definitions auto-generated from the Rust source, so the types always match runtime behavior. ## Install ```bash theme={null} npm install @simular-ai/simulang-js ``` Prebuilt native binaries are published for: | Platform | Architecture | | -------- | ----------------------------------- | | macOS | `aarch64` (Apple Silicon), `x86_64` | | Windows | `x86_64`, `aarch64` | | Linux | `x86_64`, `aarch64` (glibc) | Node.js **20 or newer** is required. If your platform isn't covered, see [Building from source](#building-from-source). ### Optional — install the log viewer The [`log-window.mjs`](_media/log-window.mjs) example uses [`@simular-ai/simulang-log-viewer`](https://github.com/simular-ai/simulang-log-viewer), which is declared as an **optional peer dependency** and **not** installed by default. Install it only if you want to run that example or use the same pattern in your own code: ```bash theme={null} npm install @simular-ai/simulang-log-viewer ``` ## Usage Try the included [`google_search.mjs`](_media/google_search.mjs) example — it opens Google in Chrome, enables the accessibility tree, takes a screenshot, and displays it: ```bash theme={null} # With the simulang CLI (no local install needed): npm install -g @simular-ai/simulang simulang run examples/google_search.mjs # Or directly with Node.js if you have simulang-js installed locally: node examples/google_search.mjs ``` ## API documentation Browse the [API reference](https://docs.simular.ai/simulang-js/api/latest/) for more details. A bleeding-edge preview of HEAD on `main` is also published to [GitHub Pages](https://simular-ai.github.io/simulang-js/) between releases. ## Using with Claude Code This package ships a short [`CLAUDE.md`](_media/CLAUDE.md) inside the npm tarball that points Claude Code at `index.d.ts` as the source of truth for the API and adds a few cross-cutting notes that types alone can't express (lifetime rules, coordinate system, etc.). Wire it into your project's `CLAUDE.md` with: ```bash theme={null} npx simulang-init-claude # appends to /CLAUDE.md (creates it if missing) npx simulang-init-claude --user # appends to ~/.claude/CLAUDE.md instead npx simulang-init-claude --check # report status, don't write ``` The added line is a single `@./node_modules/@simular-ai/simulang-js/CLAUDE.md` import inside a sentinel-delimited block — safe to re-run, no-op when already present. ## Relationship to `simulang` [`@simular-ai/simulang`](https://github.com/simular-ai/simulang-cli) is a CLI that runs desktop automation scripts (`.ts`, `.js`, `.simulang`) using this package. It bundles `simulang-js` and re-exports the full API to scripts, so you can write and run automation scripts without a build step: ```bash theme={null} npm install -g @simular-ai/simulang simulang run my-script.js ``` `simulang-js` is the underlying primitive library; `simulang` is the batteries-included script runner built on top of it. If you are embedding desktop automation into your own Node.js application, depend on `simulang-js` directly. If you just want to run standalone automation scripts, `simulang` is the easier starting point. You can also point `simulang` at a local `simulang-js` checkout during development: ```bash theme={null} simulang run --simulang-js=/path/to/simulang-js my-script.js ``` ## Enumerations | Enumeration | Description | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | [AriaRole](enumerations/AriaRole.mdx) | Cross-platform ARIA / Playwright role. Used as the `role` field on accessibility snapshots and as the search key in \[`AccessibilityTree::find`]. | | [Button](enumerations/Button.mdx) | Represents a mouse button. | | [Coordinate](enumerations/Coordinate.mdx) | Specifies if coordinates are relative or absolute. | | [Direction](enumerations/Direction.mdx) | The direction of a button event. | | [FocusPolicy](enumerations/FocusPolicy.mdx) | Focus behavior when opening an application. | | [Key](enumerations/Key.mdx) | Represents a keyboard key. | | [TraversalOrder](enumerations/TraversalOrder.mdx) | Tree traversal order for `AccessibilityTree.find()`. | | [Visibility](enumerations/Visibility.mdx) | Visibility behavior when opening an application. | ## Classes | Class | Description | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [AccessibilityNode](classes/AccessibilityNode.mdx) | A node in the platform accessibility tree. Thin binding for `simulang_rs::AXNode` (macOS `AXUIElement` / Windows UIA element / Linux AT-SPI accessible). | | [AccessibilityTree](classes/AccessibilityTree.mdx) | Accessibility tree bound to a specific window. Provides snapshot and ref-based actions for desktop automation (Windows UIA). | | [App](classes/App.mdx) | Represents an application that can be opened. | | [AskModel](classes/AskModel.mdx) | A free-form chat-completions LLM (optionally vision-capable) — the JS analogue of the `ask` primitive. | | [AudioOutput](classes/AudioOutput.mdx) | Handle to an open audio output device. Must be kept alive for playback to continue — when dropped all associated `Player`s stop producing sound. | | [Clipboard](classes/Clipboard.mdx) | Contains functions to read and write the clipboard. | | [Directory](classes/Directory.mdx) | Represents a directory handle. | | [File](classes/File.mdx) | Represents a file handle. | | [GroundingModel](classes/GroundingModel.mdx) | A visual-language grounding model that can locate concepts on images. | | [Image](classes/Image.mdx) | Represents an image. | | [Instance](classes/Instance.mdx) | Represents an opened application instance. | | [KeyboardController](classes/KeyboardController.mdx) | Contains functions to simulate key presses/releases and to input text. | | [LoopbackSource](classes/LoopbackSource.mdx) | A loopback capture source that records system audio output (what the user hears through their speakers or headphones). | | [MouseController](classes/MouseController.mdx) | 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. | | [Player](classes/Player.mdx) | Handle to a device that outputs sounds. | | [SamplesBuffer](classes/SamplesBuffer.mdx) | A buffer of samples treated as a source. | | [Screen](classes/Screen.mdx) | Represents a physical display/screen. | | [Screenshot](classes/Screenshot.mdx) | Represents a screenshot capture. | | [ScreenshotCoordinateType](classes/ScreenshotCoordinateType.mdx) | Describes how `(x, y)` coordinates passed to `Screenshot.toGlobalPhysicalPixels` should be interpreted. | | [SttModel](classes/SttModel.mdx) | A speech-to-text model that can transcribe audio. | | [System](classes/System.mdx) | Provides system-wide operations. | | [Window](classes/Window.mdx) | 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`). | ## Interfaces | Interface | Description | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | [AccessibilityNodeJs](interfaces/AccessibilityNodeJs.mdx) | - | | [BoundingBox](interfaces/BoundingBox.mdx) | Axis-aligned rectangle. `right` and `bottom` are exclusive (Playwright / DOM convention), so the box covers `[left, right) × [top, bottom)`. | | [JsLogRecord](interfaces/JsLogRecord.mdx) | A single log entry forwarded to the JS callback. | ## Functions | Function | Description | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | [ariaRoleToString](functions/ariaRoleToString.mdx) | Lowercase ARIA name for a role — matches the form used in snapshot output and accepted by `AccessibilityTree.find()`. | | [enableAccessibilityForFrontmostApp](functions/enableAccessibilityForFrontmostApp.mdx) | Enables the accessibility tree for the frontmost application. | | [hasScreenCapturePermission](functions/hasScreenCapturePermission.mdx) | - | | [initLogger](functions/initLogger.mdx) | Initialize the logger. | | [keyFromString](functions/keyFromString.mdx) | Convert a string representation into a `Key`. | | [legacyOpen](functions/legacyOpen.mdx) | Legacy helper used by Electron to open an app or URL. | | [legacyTakeScreenshot](functions/legacyTakeScreenshot.mdx) | Legacy helper used by Electron to capture a screenshot as base64. | | [readFile](functions/readFile.mdx) | Reads a file and returns its trimmed contents. | | [screenshotCropped](functions/screenshotCropped.mdx) | Takes the screenshot of a cropped region of the workspace. | | [screenshotFull](functions/screenshotFull.mdx) | Takes the screenshot of the entire selected screen | | [writeFile](functions/writeFile.mdx) | Writes content to a file, returning the absolute path written to. |