@rebind.gg/mcp-server 0.1.4 → 0.1.6

package/README.md

@@ -1,19 +1,17 @@
 # @rebind.gg/mcp-server
 
-Stdio MCP server that exposes Rebind as computer-use tools: `screenshot`,
-`screenshot_window`, `zoom`, `click` (verified), `move_mouse`, `type`, `key`,
-`scroll`, `run_lua`, `wait`, window control, and `calibrate`. Wraps
-`@rebind.gg/client-ts`; requires the **Rebind** app
-(https://rebind.gg/download) running its Remote Access relay — `remote.luau`
-(recommended) or `remote_access.lua` (protocol >= 1.1.0). The `click` tool clicks via `hid.press`, which is
-coroutine-only; use `remote.luau` or a current `remote_access.lua` (older copies
-called it outside a coroutine, so clicks silently failed).
+Stdio MCP server that turns [Rebind](https://rebind.gg) into a computer-use toolkit: screenshots, verified clicks, keyboard input, window control, and direct Luau scripting on the connected machine — driven over real HID, not synthetic OS events.
+
+**Requirements**
+
+- [Bun](https://bun.sh) >= 1.1 (the server runs via `bunx`)
+- The [Rebind app](https://rebind.gg/download) running its Remote Access relay: `remote.luau` (recommended) or `remote_access.lua` (protocol >= 1.1.0)
+
+> Older copies of `remote_access.lua` called `hid.press` outside a coroutine, so clicks silently failed. Use `remote.luau` or a current `remote_access.lua`.
 
 ## Install
 
-One command writes the correct config for whichever clients you name — Claude
-Code, Cursor, Codex, OpenCode, VS Code, Windsurf, Zed, and more — each in its
-native format, via [`add-mcp`](https://github.com/neondatabase/add-mcp):
+One command writes the correct config for whichever clients you name — Claude Code, Cursor, Codex, OpenCode, VS Code, Windsurf, Zed, and more — via [`add-mcp`](https://github.com/neondatabase/add-mcp):
 
 ```sh
 npx add-mcp "bunx @rebind.gg/mcp-server" --name rebind \
@@ -21,13 +19,9 @@ npx add-mcp "bunx @rebind.gg/mcp-server" --name rebind \
   -g -a claude-code -a cursor -a codex -a opencode
 ```
 
-Drop `-a <agent>` for the clients you want, or pass `--all`. `-g` installs
-globally; omit it for project-local config. Restart the client afterward.
-
-Requires **Bun** (the server runs via `bunx`) and the **Rebind** app
-(https://rebind.gg/download) running its Remote Access relay.
+Drop `-a <agent>` for the clients you want, or pass `--all`. `-g` installs globally; omit it for project-local config. Restart the client afterward.
 
-## Configure manually
+### Manual configuration
 
 Any MCP client takes the stdio block directly:
 
@@ -43,33 +37,48 @@ Any MCP client takes the stdio block directly:
 }
 ```
 
-`REBIND_TOKEN` is required when the server has an auth token set (the **Auth
-token** panel field on `remote.luau`, or `AUTH_TOKEN` on `remote_access.lua`).
-
-Check the relay is reachable before wiring it up:
+### Verify the relay is reachable
 
 ```sh
 bunx @rebind.gg/mcp-server --selftest
 ```
 
-Set `REBIND_AGENT_LOG=<path>` to append one JSONL line per tool call
-(`{ts, tool, ok, latency_ms, note}`) — no screenshot bytes, no user content.
-Off unless set.
-
-`click` and `move_mouse` reach an absolute screen point by reading the real OS
-cursor and sending relative HID deltas (which map 1:1 to pixels), correcting
-against the true cursor until it lands. This sidesteps the relay's own absolute
-move, whose delta is computed from a cached cursor position that goes stale and
-flings the pointer to a screen edge. A mouse scale probe runs on the first
-click/move_mouse; if pointer ballistics are detected (enhance pointer precision,
-DPI mismatch) the probe reports it, since acceleration would break the 1:1
-assumption.
-
-Tool calls are serialized through a single queue: there is one physical cursor
-and keyboard, so parallel tool calls from the model (e.g. two `move_mouse` in
-one turn) run one after another instead of interleaving HID input. All results
-are reported in the coordinate space of the last screenshot, the same space the
-model emits.
+Connects, takes a capture, and reports the display — the fastest way to catch the #1 first-run failure (relay not loaded).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `screenshot` | Capture a display (cursor marked with a crosshair). All coordinates the model emits are pixels in the most recent screenshot. |
+| `screenshot_window` | Capture one window by title substring (or the active window) — smaller, cheaper, monitor-proof. |
+| `zoom` | Re-capture a region of the last screenshot at native resolution, for small text. Read-only. |
+| `click` | Move to a point and click (`left`/`right`/`middle`, optional double). Landing position is verified and corrected before pressing. |
+| `move_mouse` | Move without clicking, with the same verification. |
+| `type` | Type text into the focused element. |
+| `key` | Press a key or combo, e.g. `Enter`, `LCtrl+L`, `LAlt+Tab`. |
+| `scroll` | Scroll the wheel at the cursor (positive = up). |
+| `run_lua` | Run a Luau script on the connected machine and return its `return` value as JSON — the fast path for any deterministic sequence (launch apps, place windows, shell commands, pixel search). |
+| `lua_docs` | Full Luau SDK type definitions for `run_lua`. |
+| `list_displays` / `list_windows` / `focus_window` / `active_window` | Display and window enumeration and control. |
+| `get_cursor` / `wait` / `calibrate` | Cursor readback, pauses, and the mouse scale probe. |
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `REBIND_URL` | `ws://127.0.0.1:19561` | Relay WebSocket URL. |
+| `REBIND_TOKEN` | — | Required when the relay has an auth token set (the **Auth token** panel field on `remote.luau`, or `AUTH_TOKEN` on `remote_access.lua`). |
+| `REBIND_AGENT_LOG` | off | Path to append one JSONL line per tool call (`{ts, tool, ok, latency_ms, note}`). No screenshot bytes, no user content. |
+
+## How it works
+
+**Verified clicks.** `click` and `move_mouse` reach an absolute screen point by reading the real OS cursor and sending relative HID deltas (which map 1:1 to pixels), correcting against the true cursor until it lands. This sidesteps the relay's own absolute move, whose delta comes from a cached cursor position that goes stale and flings the pointer to a screen edge.
+
+**Calibration.** A mouse scale probe runs on the first `click`/`move_mouse`. If pointer ballistics are detected (enhance pointer precision, DPI mismatch), the probe reports it, since acceleration would break the 1:1 assumption. Re-run it any time with `calibrate`.
+
+**One queue.** There is one physical cursor and keyboard, so tool calls are serialized: parallel calls from the model run one after another instead of interleaving HID input.
+
+**One coordinate space.** All results are reported in the pixel space of the last screenshot — the same space the model emits — so no rescaling math ever falls on the model.
 
 ## Develop
 
@@ -77,3 +86,7 @@ model emits.
 bun test packages/mcp-server/tests/
 bun run --cwd packages/mcp-server typecheck
 ```
+
+## License
+
+MIT © [US Input Company](https://usinput.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebind.gg/mcp-server",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "MCP server exposing Rebind as computer-use tools: screenshot, verified click, type, key, scroll, and window control over the Remote Access protocol.",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@rebind.gg/client-ts": "0.2.0",
+    "@rebind.gg/client-ts": "0.2.1",
     "sharp": "^0.34.2",
     "zod": "^3.25.0"
   },

package/src/index.ts

@@ -53,7 +53,7 @@ async function main() {
 
   const session = new Session(client);
 
-  const server = new McpServer({ name: "rebind", version: "0.1.4" });
+  const server = new McpServer({ name: "rebind", version: "0.1.6" });
 
   // REBIND_AGENT_LOG=<path>: opt-in telemetry — one JSONL line per tool call
   // ({ts, tool, ok, latency_ms, note}). No screenshot bytes, no user content.
@@ -101,7 +101,8 @@ async function main() {
       description:
         "Capture a display and return it as an image. The cursor is marked with a red crosshair. " +
         "All click/move coordinates you emit must be pixel coordinates in the MOST RECENT screenshot. " +
-        "After every action, take a new screenshot and verify the action had the intended effect before continuing; if not, correct and retry.",
+        "After every action, take a new screenshot and verify the action had the intended effect before continuing; if not, correct and retry. " +
+        "Identify UI elements (labels, inputs, search boxes) before acting; prefer type/key over blind clicking.",
       inputSchema: {
         display: z
           .number()
@@ -224,7 +225,8 @@ async function main() {
     {
       description:
         "Capture a region of the last screenshot at full native resolution, for reading small text or inspecting small targets. " +
-        "READ-ONLY: click coordinates still refer to the last full screenshot, not the zoomed image.",
+        "READ-ONLY: click coordinates still refer to the last full screenshot, not the zoomed image. " +
+        "Useful to check cursor-target alignment when a click missed.",
       inputSchema: {
         x: z
           .number()
@@ -288,7 +290,8 @@ async function main() {
     {
       description:
         "Move the mouse to a point in the last screenshot and click. The landing position is verified and corrected before pressing. " +
-        "Prefer keyboard shortcuts (the key tool) for fiddly widgets like address bars and dropdowns.",
+        "Prefer keyboard shortcuts (the key tool) for fiddly widgets like address bars and dropdowns. " +
+        "Identify the target (read its label/text) before clicking, and confirm the effect with a screenshot after.",
       inputSchema: {
         x: z.number().describe("x in last-screenshot image pixels"),
         y: z.number().describe("y in last-screenshot image pixels"),
@@ -314,7 +317,8 @@ async function main() {
     "move_mouse",
     {
       description:
-        "Move the mouse to a point in the last screenshot without clicking.",
+        "Move the mouse to a point in the last screenshot without clicking. " +
+        "If the response warns the cursor stopped short, take a fresh screenshot and retry.",
       inputSchema: {
         x: z.number().describe("x in last-screenshot image pixels"),
         y: z.number().describe("y in last-screenshot image pixels"),
@@ -337,7 +341,9 @@ async function main() {
   register(
     "type",
     {
-      description: "Type text into the focused element via the keyboard.",
+      description:
+        "Type text into the focused element via the keyboard. " +
+        "Use LCtrl+A / LMeta+A (key tool) to select all first when replacing existing text.",
       inputSchema: { text: z.string() },
     },
     async ({ text: t }) => {
@@ -353,7 +359,8 @@ async function main() {
     {
       description:
         'Press a key or combo. Names: "Enter", "Escape", "Tab", "Backspace", arrows ("Up", "Down", "Left", "Right"), letters/digits, modifiers "LCtrl", "LAlt", "LShift", "LMeta". ' +
-        'Combos join with "+", e.g. "LCtrl+L" (focus address bar), "LCtrl+C", "LAlt+Tab".',
+        'Combos join with "+", e.g. "LCtrl+L" (focus address bar), "LCtrl+C", "LAlt+Tab". ' +
+        'Useful shortcuts: Space/PageDown/PageUp to scroll, LCtrl+F or LMeta+F to find text on the page, Escape to close dialogs.',
       inputSchema: { combo: z.string() },
     },
     async ({ combo }) => {
@@ -367,7 +374,8 @@ async function main() {
     "scroll",
     {
       description:
-        "Scroll the mouse wheel at the current cursor position. Positive = up, negative = down.",
+        "Scroll the mouse wheel at the current cursor position. Positive = up, negative = down. " +
+        "Key shortcuts (Space, PageDown/PageUp, arrows) are often more reliable for page-level scrolling.",
       inputSchema: { clicks: z.number().int().describe("wheel clicks") },
     },
     async ({ clicks }) => {
@@ -397,8 +405,31 @@ async function main() {
       inputSchema: { handle: z.number() },
     },
     async ({ handle }) => {
-      await client.windowActivate(handle);
-      return text(`activated window ${handle}`);
+      // handle-based activation can raise without focusing on macOS; fall back
+      // to app-name activation (App.Activate, macOS-only, no-op elsewhere via
+      // pcall). Decided relay-side: this process may run on a different
+      // machine than the relay, so process.platform is the wrong signal.
+      const r = (await client.luaExec(`
+local h = ${handle}
+Window.Activate(h)
+Sleep(150)
+if Window.IsActive(h) then return { ok = true } end
+local name
+for _, w in ipairs(Window.List()) do
+  if w.handle == h then name = w.process; break end
+end
+if not name then return { ok = false, err = "window handle not found" } end
+pcall(function() App.Activate(name) end)
+Sleep(150)
+return { ok = Window.IsActive(h), name = name }
+`)) as { ok?: boolean; name?: string; err?: string };
+      if (r.ok)
+        return text(
+          `activated window ${handle}${r.name ? ` via app "${r.name}"` : ""}`,
+        );
+      return text(
+        `WARNING: window ${handle} ${r.err ?? "may not be focused"} — verify with active_window or a screenshot`,
+      );
     },
   );
 
@@ -445,7 +476,8 @@ async function main() {
         "reliable, and it sidesteps multi-monitor guessing. Use it to: launch apps (`System.ExecDetached(\"cmd\", {\"/c\",\"start\",\"\",url})`), " +
         "wait for and place windows on a known display (`local h=Window.Wait(title, ms); Window.Move(h, x, y, w, h)`), " +
         "run shell commands (`System.Exec(cmd) -> {exit,stdout,stderr}`), find UI by color (`Screen.SearchForColor(region,hex)`), " +
-        "type, click, read pixels, manage processes. Namespaces: System, HID, Input, Screen, Window, Process, File, Clipboard, Net, Macro, Env, Log. " +
+        "type, click, read pixels, manage processes. Namespaces: System, HID, Input, Screen, Window, App, Process, File, Clipboard, Net, Macro, Env, Log; global Sleep(ms). " +
+        "Call `lua_docs` for exact signatures BEFORE writing nontrivial scripts — do not guess APIs. " +
         "Fall back to `screenshot` only for genuinely visual reasoning the script cannot resolve. End the script with `return <value>` to get data back.",
       inputSchema: {
         source: z
@@ -461,6 +493,19 @@ async function main() {
     },
   );
 
+  register(
+    "lua_docs",
+    {
+      description:
+        "Return the full Luau SDK type definitions for run_lua: every namespace, function signature, and type. " +
+        "Read this before writing any nontrivial run_lua script instead of guessing APIs.",
+    },
+    // byte-identical copy of packages/lua-sdk/types/rebind.d.luau, shipped in
+    // the package; tests/lua-docs-sync.test.ts guards against drift
+    async () =>
+      text(await Bun.file(new URL("./rebind.d.luau", import.meta.url)).text()),
+  );
+
   await server.connect(new StdioServerTransport());
   // stdout carries the MCP protocol — log to stderr only
   console.error(

package/src/rebind.d.luau

@@ -0,0 +1,698 @@
+-- rebind sdk type definitions for luau language server
+-- provides autocomplete, hover docs, and type checking for all sdk namespaces.
+-- reference this file in your .luaurc: { "languageMode": "strict", "paths": ["types"] }
+
+-- handle types
+
+export type TaskHandle = {
+  Cancel: (self: TaskHandle) -> (),
+  IsRunning: (self: TaskHandle) -> boolean,
+}
+
+export type TimerHandle = {
+  Cancel: (self: TimerHandle) -> (),
+  Pause: (self: TimerHandle) -> (),
+  Resume: (self: TimerHandle) -> (),
+}
+
+export type MacroHandle = {
+  Stop: (self: MacroHandle) -> (),
+  Pause: (self: MacroHandle) -> (),
+  Resume: (self: MacroHandle) -> (),
+  IsPlaying: (self: MacroHandle) -> boolean,
+  GetProgress: (self: MacroHandle) -> number,
+}
+
+export type BindHandle = {
+  unbind: (self: BindHandle) -> (),
+  disable: (self: BindHandle) -> (),
+  enable: (self: BindHandle) -> (),
+  enabled: boolean,
+}
+
+export type ServerHandle = {
+  port: number,
+  Stop: (self: ServerHandle) -> (),
+}
+
+-- WebSocket: server-side per-connection handle passed to OnConnect/OnMessage/OnClose.
+-- `id` is a monotonic identifier unique to this connection.
+export type WsClient = {
+  id: number,
+  Send: (self: WsClient, text: string) -> (),
+  SendBinary: (self: WsClient, bytes: string) -> (),
+  Close: (self: WsClient) -> (),
+}
+
+-- WebSocket: server handle returned by Net.WSListen.
+export type WsServerHandle = {
+  port: number,
+  Broadcast: (self: WsServerHandle, text: string) -> (),
+  BroadcastBinary: (self: WsServerHandle, bytes: string) -> (),
+  ClientCount: (self: WsServerHandle) -> number,
+  Stop: (self: WsServerHandle) -> (),
+}
+
+-- WebSocket: outbound-connection handle returned by Net.WSConnect.
+export type WsConnectHandle = {
+  Send: (self: WsConnectHandle, text: string) -> (),
+  SendBinary: (self: WsConnectHandle, bytes: string) -> (),
+  Close: (self: WsConnectHandle) -> (),
+}
+
+-- WebSocket: server event-handler table passed to Net.WSListen.
+-- All fields are optional; handlers that are absent are never called.
+export type WsListenHandlers = {
+  OnConnect: ((client: WsClient) -> ())?,
+  OnMessage: ((client: WsClient, payload: string, isBinary: boolean) -> ())?,
+  OnClose: ((client: WsClient) -> ())?,
+}
+
+-- WebSocket: client event-handler table passed to Net.WSConnect.
+export type WsConnectHandlers = {
+  OnOpen: (() -> ())?,
+  OnMessage: ((payload: string, isBinary: boolean) -> ())?,
+  OnClose: (() -> ())?,
+}
+
+export type PipeHandle = {
+  name: string,
+  size: number,
+  capacity: number,
+  Read: (self: PipeHandle) -> string?,
+  Write: (self: PipeHandle, data: string) -> (),
+  Close: (self: PipeHandle) -> (),
+}
+
+-- data types
+
+export type WindowInfo = {
+  title: string,
+  process: string,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+}
+
+export type WindowEntry = {
+  handle: number,
+  title: string,
+  process: string,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+}
+
+export type WindowPos = {
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+}
+
+export type MousePos = {
+  x: number,
+  y: number,
+}
+
+export type ModifierState = {
+  ctrl: boolean,
+  shift: boolean,
+  alt: boolean,
+  win: boolean,
+}
+
+export type HttpResponse = {
+  status: number,
+  body: string,
+  headers: { [string]: string },
+}
+
+-- `body` may contain arbitrary bytes (Luau strings are byte strings).
+export type HttpRequest = {
+  method: string,
+  path: string,
+  body: string,
+  headers: { [string]: string },
+}
+
+-- `body` may contain arbitrary bytes; set a Content-Type header for binary.
+export type HttpResponseSpec = {
+  status: number?,
+  body: string?,
+  headers: { [string]: string }?,
+}
+
+export type HttpOptions = {
+  timeout: number?,
+}
+
+export type HttpRequestOptions = {
+  method: string,
+  url: string,
+  body: string?,
+  headers: { [string]: string }?,
+  timeout: number?,
+}
+
+-- macro action types
+
+export type MacroMoveAction = {
+  x: number,
+  y: number,
+  delay: number,
+}
+
+export type MacroExplicitAction = {
+  action: string,
+  code: string?,
+  dx: number?,
+  dy: number?,
+  x: number?,
+  y: number?,
+  text: string?,
+  amount: number?,
+  holdMs: number?,
+  charDelay: number?,
+  delay: number,
+}
+
+export type MacroAction = MacroMoveAction | MacroExplicitAction
+
+-- ui widget option types
+
+export type ToggleOpts = {
+  label: string?,
+}
+
+export type SliderOpts = {
+  label: string?,
+  min: number?,
+  max: number?,
+  step: number?,
+  suffix: string?,
+  tooltip: string?,
+  group: string?,
+  tab: string?,
+  showIf: string?,
+}
+
+export type KeybindOpts = {
+  label: string?,
+}
+
+export type SelectOpts = {
+  label: string?,
+}
+
+export type TextOpts = {
+  label: string?,
+  placeholder: string?,
+  maxLength: number?,
+  tooltip: string?,
+  group: string?,
+  tab: string?,
+  showIf: string?,
+}
+
+export type ColorOpts = {
+  label: string?,
+  tooltip: string?,
+  group: string?,
+  tab: string?,
+  showIf: string?,
+}
+
+export type RecordOpts = {
+  ignore_mouse: boolean?,
+  ignore_keyboard: boolean?,
+  precision: string?,
+}
+
+-- ui proxy: returned by UI.Schema, supports dynamic field access
+-- cfg.key reads the current value, cfg.key = value writes it
+export type UiProxy = { [string]: any }
+
+-- bind config for table-style binding
+export type BindConfig = {
+  when: (() -> boolean)?,
+  action: (() -> boolean?)?,
+  release: (() -> ())?,
+}
+
+-- runtime identity table
+export type RebindInfo = {
+  min_sdk: string,
+  tick_rate: number,
+  version: string,
+  name: string,
+  runtime_uuid: string,
+  id: string?,
+  instance: string,
+}
+
+-- global functions
+
+declare function Run(fn: () -> ()): TaskHandle
+-- RunAsync was removed. Use Run() directly.
+declare function Sleep(ms: number): ()
+declare function After(ms: number, fn: () -> ()): TaskHandle
+declare function Async(fn: (...any) -> ...any): (...any) -> ...any
+declare function print(...: any): ()
+declare function require(module: string): any
+
+-- global tables
+
+declare _REBIND: RebindInfo
+
+-- system namespace
+
+export type ExecOptions = {
+  timeout: number?,
+  cwd: string?,
+}
+
+export type ExecResult = {
+  exit: number,
+  stdout: string,
+  stderr: string,
+}
+
+export type ExecDetachedOptions = {
+  cwd: string?,
+}
+
+declare System: {
+  Time: () -> number,
+  Mouse: () -> (number, number),
+  Screen: () -> (number, number),
+  Window: () -> WindowInfo,
+  Exec: (cmd: string, options: ExecOptions?) -> ExecResult,
+  ExecDetached: (cmd: string, args: { string }?, options: ExecDetachedOptions?) -> number,
+}
+
+-- hid namespace
+
+declare HID: {
+  Down: (code: string) -> (),
+  Up: (code: string) -> (),
+  Press: (code: string, holdMs: number?) -> (),
+  -- fire a chord in one synchronous call (press L→R, release R→L). no sleep,
+  -- so callable directly from a Bind action / OnDown. modifier tokens accept
+  -- macOS aliases: "cmd", "opt"/"option", plus "ctrl"/"shift"/"alt"/"win".
+  Combo: (code: string) -> (),
+  -- instant whole-string insertion (native; no coroutine). For a human-like
+  -- per-character typewriter effect use Typewriter (coroutine-only).
+  Type: (text: string) -> (),
+  Typewriter: (text: string, delayMs: number?) -> (),
+  Move: (dx: number, dy: number) -> (),
+  MoveTo: (x: number, y: number) -> (),
+  Scroll: (amount: number) -> (),
+  SetMouseMode: (mode: string) -> (),
+  GetMouseMode: () -> string,
+}
+
+-- input namespace
+
+declare Input: {
+  IsDown: (code: string) -> boolean,
+  GetDuration: (code: string) -> number,
+  GetActiveKeys: () -> { string },
+  GetMousePos: () -> MousePos,
+  GetModifiers: () -> ModifierState,
+}
+
+-- ui namespace
+
+declare UI: {
+  Schema: (descriptors: { [string]: any }) -> UiProxy,
+  Toggle: (default: boolean, opts: ToggleOpts?) -> any,
+  Slider: (default: number, opts: SliderOpts?) -> any,
+  Keybind: (default: string, opts: KeybindOpts?) -> any,
+  Select: (default: string, choices: { string }, opts: SelectOpts?) -> any,
+  Text: (default: string, opts: TextOpts?) -> any,
+  Color: (default: string, opts: ColorOpts?) -> any,
+  Get: (id: string) -> any,
+  Set: (id: string, value: any) -> (),
+  GetAll: () -> { [string]: any },
+  GetSchema: () -> { any },
+  Notify: (text: string, variant: string?) -> (),
+}
+
+-- bind namespace (callable table)
+
+declare Bind: typeof(setmetatable({} :: {
+  Toggle: (key: string, uiId: string) -> BindHandle,
+  Remap: (from: string, to: string) -> BindHandle,
+}, {} :: {
+  __call: (self: any, key: string, config: (() -> boolean?) | BindConfig) -> BindHandle,
+}))
+
+-- timer namespace
+
+declare Timer: {
+  After: (ms: number, callback: () -> ()) -> TimerHandle,
+  Every: (ms: number, callback: () -> ()) -> TimerHandle,
+  CancelAll: () -> (),
+}
+
+-- macro namespace
+
+declare Macro: {
+  Play: (macro: { MacroAction }, speed: number?, mode: string?) -> MacroHandle,
+  StopAll: () -> (),
+  Record: (options: RecordOpts?) -> (),
+  Finish: () -> { MacroAction },
+  Stream: (macro: { MacroAction }) -> (),
+  Abort: () -> (),
+}
+
+-- math namespace
+
+declare Math: {
+  Random: (min: number, max: number) -> number,
+  Gaussian: (mean: number, stdDev: number) -> number,
+  Scale: (macro: { MacroAction }, xFactor: number, yFactor: number) -> { MacroAction },
+  Spline: (macro: { MacroAction }, tension: number) -> { MacroAction },
+  Resample: (macro: { MacroAction }, intervalMs: number) -> { MacroAction },
+  TimeComp: (macro: { MacroAction }, targetMs: number) -> { MacroAction },
+  Interpolate: (macro: { MacroAction }, intervalMs: number, mode: string?) -> { MacroAction },
+}
+
+-- log namespace
+
+declare Log: {
+  Info: (msg: string) -> (),
+  Warn: (msg: string) -> (),
+  Error: (msg: string) -> (),
+  Debug: (msg: string) -> (),
+}
+
+-- json namespace
+
+declare JSON: {
+  Parse: (s: string) -> any,
+  Stringify: (value: any) -> string,
+}
+
+-- process namespace
+
+export type ProcessEntry = {
+  pid: number,
+  name: string,
+}
+
+declare Process: {
+  Exists: (name: string) -> number?,
+  List: (name: string?) -> { ProcessEntry },
+  Kill: (pid: number) -> boolean,
+}
+
+-- screen namespace
+
+export type PixelMatch = {
+  x: number,
+  y: number,
+}
+
+export type MonitorEntry = {
+  index: number,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  primary: boolean,
+}
+
+declare Screen: {
+  GetPixelColor: (x: number?, y: number?) -> string,
+  SearchForColor: (region: {number}, color: string, tolerance: number?) -> PixelMatch?,
+  List: () -> { MonitorEntry },
+}
+
+-- window namespace
+
+declare Window: {
+  Find: (title: string) -> number?,
+  List: (title: string?) -> { WindowEntry },
+  GetTitle: (handle: number?) -> string,
+  GetClass: (handle: number?) -> string,
+  GetPos: (handle: number?) -> WindowPos,
+  GetPID: (handle: number?) -> number,
+  Activate: (handle: number) -> (),
+  Move: (handle: number, x: number?, y: number?, width: number?, height: number?) -> (),
+  SetAlwaysOnTop: (handle: number, enabled: boolean) -> (),
+  SetTransparency: (handle: number, alpha: number) -> (),
+  SetTitle: (handle: number, title: string) -> (),
+  Minimize: (handle: number?) -> (),
+  Maximize: (handle: number?) -> (),
+  Restore: (handle: number?) -> (),
+  Hide: (handle: number?) -> (),
+  Show: (handle: number?) -> (),
+  Close: (handle: number?) -> (),
+  Kill: (handle: number?) -> (),
+  IsVisible: (handle: number) -> boolean,
+  IsActive: (handle: number?) -> boolean,
+  Wait: (title: string, timeout: number?) -> number?,
+  WaitActive: (title: string, timeout: number?) -> boolean,
+  WaitClose: (title: string, timeout: number?) -> boolean,
+}
+
+-- app namespace: application-level control (Keyboard Maestro's Application
+-- Control). names match case-insensitively by app display name. Front/IsRunning/
+-- Activate are permission-free; Hide/Quit/IsHidden drive an AppleEvent and
+-- prompt for macOS Automation permission on first use.
+
+export type AppInfo = {
+  name: string,
+  pid: number,
+}
+
+declare App: {
+  Front: () -> AppInfo?,
+  IsFront: (name: string) -> boolean,
+  IsRunning: (name: string) -> boolean,
+  IsHidden: (name: string) -> boolean,
+  Activate: (name: string) -> (),
+  Hide: (name: string) -> (),
+  Quit: (name: string) -> (),
+}
+
+-- net namespace
+
+declare Net: {
+  Get: (url: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
+  Post: (url: string, body: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
+  Put: (url: string, body: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
+  Patch: (url: string, body: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
+  Delete: (url: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
+  Head: (url: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
+  Request: (options: HttpRequestOptions) -> HttpResponse,
+  Listen: (port: number, handler: (request: HttpRequest) -> HttpResponseSpec | string) -> ServerHandle,
+  WSListen: (port: number, handlers: WsListenHandlers) -> WsServerHandle,
+  WSConnect: (url: string, handlers: WsConnectHandlers) -> WsConnectHandle,
+}
+
+-- pipe namespace
+
+declare Pipe: {
+  Open: (name: string, options: { size: number? }?) -> PipeHandle,
+}
+
+-- file namespace
+
+declare File: {
+  Read: (path: string) -> string,
+  ReadBytes: (path: string) -> string,
+  Write: (path: string, content: string) -> (),
+  Append: (path: string, content: string) -> (),
+  Exists: (path: string) -> boolean,
+  Delete: (path: string) -> boolean,
+  List: (path: string?) -> { string },
+  MkDir: (path: string) -> boolean,
+  RmDir: (path: string) -> (),
+  ReadJSON: (path: string) -> any,
+  WriteJSON: (path: string, value: any) -> (),
+  GetScriptDir: () -> string,
+  GetSize: (path: string) -> number,
+  GetTime: (path: string) -> number,
+  Copy: (src: string, dst: string) -> (),
+  Move: (src: string, dst: string) -> (),
+  IsDir: (path: string) -> boolean,
+  IsFile: (path: string) -> boolean,
+}
+
+-- audio namespace
+
+export type PlayOptions = {
+  volume: number?,
+  loop: boolean?,
+}
+
+export type SoundHandle = {
+  Stop: (self: SoundHandle) -> (),
+  Pause: (self: SoundHandle) -> (),
+  Resume: (self: SoundHandle) -> (),
+  IsPlaying: (self: SoundHandle) -> boolean,
+  SetVolume: (self: SoundHandle, vol: number) -> (),
+  GetVolume: (self: SoundHandle) -> number,
+}
+
+declare Audio: {
+  Beep: () -> (),
+  Play: (path: string, options: PlayOptions?) -> SoundHandle,
+  StopAll: () -> (),
+  SetMasterVolume: (vol: number) -> (),
+  GetMasterVolume: () -> number,
+}
+
+-- dialog namespace
+
+export type DialogMessageOptions = {
+  title: string?,
+  level: string?,
+}
+
+export type DialogFileFilter = {
+  name: string,
+  extensions: { string },
+}
+
+export type DialogFileOptions = {
+  title: string?,
+  location: string?,
+  filters: { DialogFileFilter }?,
+}
+
+declare Dialog: {
+  Message: (text: string, options: DialogMessageOptions?) -> (),
+  Confirm: (text: string, options: DialogMessageOptions?) -> boolean,
+  OpenFile: (options: DialogFileOptions?) -> string?,
+  OpenDir: (options: DialogFileOptions?) -> string?,
+  SaveFile: (options: DialogFileOptions?) -> string?,
+}
+
+-- clipboard namespace
+
+declare Clipboard: {
+  Get: () -> string?,
+  Set: (text: string) -> (),
+}
+
+-- script namespace
+
+declare Script: {
+  Exit: (reason: string?) -> (),
+  Reload: () -> (),
+}
+
+-- regex namespace
+
+export type RegexMatch = {
+  match: string,
+  captures: { string },
+  start: number,
+  finish: number,
+}
+
+declare Regex: {
+  IsMatch: (text: string, pattern: string) -> boolean,
+  Find: (text: string, pattern: string) -> RegexMatch?,
+  FindAll: (text: string, pattern: string) -> { RegexMatch },
+  Replace: (text: string, pattern: string, replacement: string) -> string,
+  ReplaceAll: (text: string, pattern: string, replacement: string) -> string,
+  Split: (text: string, pattern: string) -> { string },
+}
+
+-- config namespace
+
+declare Config: {
+  ParseTOML: (text: string) -> { [string]: any },
+  ToTOML: (value: { [string]: any }) -> string,
+  ReadTOML: (path: string) -> { [string]: any },
+  WriteTOML: (path: string, value: { [string]: any }) -> (),
+}
+
+-- hash namespace
+
+declare Hash: {
+  MD5: (data: string) -> string,
+  SHA1: (data: string) -> string,
+  SHA256: (data: string) -> string,
+  SHA512: (data: string) -> string,
+  CRC32: (data: string) -> number,
+  HMAC: (algo: string, key: string, data: string) -> string,
+}
+
+-- codec namespace
+
+declare Codec: {
+  Base64: (data: string) -> string,
+  Base64Decode: (str: string) -> string,
+  Hex: (data: string) -> string,
+  HexDecode: (str: string) -> string,
+}
+
+-- env namespace
+
+declare Env: {
+  Get: (name: string) -> string?,
+  Set: (name: string, value: string) -> (),
+  Home: () -> string?,
+  Config: () -> string?,
+  Data: () -> string?,
+  Desktop: () -> string?,
+  Documents: () -> string?,
+  Downloads: () -> string?,
+  AppData: () -> string?,
+  Temp: () -> string?,
+}
+
+-- registry namespace (windows only)
+
+declare Registry: {
+  Read: (keyPath: string, valueName: string) -> string | number,
+  Write: (keyPath: string, type: string, valueName: string, value: any) -> (),
+  DeleteValue: (keyPath: string, valueName: string) -> (),
+  DeleteKey: (keyPath: string) -> (),
+  CreateKey: (keyPath: string) -> (),
+}
+
+-- valid key names for input hooks (OnDown, OnUp):
+--
+-- letters:     A-Z
+-- numbers:     0-9
+-- function:    F1-F12
+-- mouse:       Mouse1 (left), Mouse2 (right), Mouse3 (middle), Mouse4, Mouse5
+-- modifiers:   LCtrl, RCtrl, LShift, RShift, LAlt, RAlt, LWin, RWin
+-- navigation:  Up, Down, Left, Right, Home, End, PageUp, PageDown, Insert, Delete
+-- editing:     Backspace, Tab, Enter, Space, Escape
+-- punctuation: Minus, Equal, LeftBrace, RightBrace, Backslash, Semicolon,
+--              Apostrophe, Grave, Comma, Period, Slash
+-- locks:       CapsLock, ScrollLock, NumLock
+-- system:      PrintScreen, Pause, Menu
+-- numpad:      Kp0-Kp9, KpPlus, KpMinus, KpMultiply, KpDivide, KpEnter, KpDot
+--
+-- HID output only (HID.Down, HID.Press, etc.):
+-- function:    F13-F24
+-- media:       MediaNext, MediaPrev, MediaStop, MediaPlay, VolumeUp, VolumeDown, Mute
+-- aliases:     Numpad0-9, NP0-9, NPAdd, NPSubtract, NPMultiply, NPDivide, NPEnter,
+--              NPDecimal, Ctrl, Shift, Alt, Win, Meta, Del, PgUp, PgDn, etc.
+
+-- hooks: declare these as global functions in your script.
+-- uncomment the ones you use; the runtime calls them when events occur.
+
+-- declare function OnStart(): ()
+-- declare function OnStop(): ()
+-- declare function OnFocus(window: WindowInfo): ()
+-- declare function OnBlur(window: WindowInfo): ()
+-- declare function OnTick(dtMs: number): ()  -- ms elapsed since the previous OnTick (0 on the first)
+-- declare function OnDown(key: string): boolean?
+-- declare function OnUp(key: string, durationMs: number): boolean?
+-- declare function OnMove(dx: number, dy: number): boolean?  -- return value only used with mouse_block=true (hardware mode only)
+-- declare function OnScroll(delta: number): boolean?
+-- declare function OnScrollH(delta: number): boolean?
+-- declare function OnError(): ()
+-- declare function OnReload(): ()