simulang-js CLAUDE.md

@simular-ai/simulang-js

Node.js bindings for the Rust simulang-rs crate (via napi-rs). Cross-platform automation of desktops and Android devices: apps, windows, accessibility trees, mouse/keyboard, screenshots, clipboard, audio, and VLM/LLM/STT model access.

This file ships in the npm tarball alongside index.d.ts and is versioned with it.

Where the API is documented

Read index.d.ts first — it is the source of truth. Every class, function, and enum is fully typed (~2100 lines) and carries JSDoc covering idioms, lifecycle rules, platform quirks, and inter-API trade-offs that types alone can't express. The JSDoc is generated from doc comments, so the per-symbol guidance there is authoritative — trust it over any restatement elsewhere.

Mental model

• Machine is the entry point. Machine.local() is the desktop this process runs on; Machine.android(endpoint) is an Android device driven over adb from the host. Apps, windows, and accessibility nodes are obtained from a machine and stay bound to it; mouse, keyboard, and clipboard access are flat methods on the machine itself (moveMouse, typeText, getClipboardString, …). The same code drives any backend — write against Machine and the handles it returns, and only reach for machine.asAndroid() when an operation has no desktop counterpart.
• Calls into the native module are synchronous. No Promises are returned; Result::Err on the Rust side is translated to a thrown JS exception by napi-rs, so JS callers try/catch as usual.
• Many objects are handles to platform resources (windows, audio devices, accessibility trees, file/directory handles). Their lifetime matters; dropping them can free the underlying resource.
• Coordinates live on the global desktop: top-left origin at (0, 0) on the primary monitor (on Android, the device screen), in OS-native units — the unit is not the same on every platform:
  • Windows / Linux / Android: physical pixels (raw hardware pixels).
  • macOS: logical points — on a 2× Retina display one point spans two hardware pixels, so a 1920×1080-logical screen is 1920×1080 here, not 3840×2160.