@rebind.gg/mcp-server 0.1.3 → 0.1.5

package/README.md

@@ -60,9 +60,16 @@ Off unless set.
 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 still runs at startup;
-if pointer ballistics are detected (enhance pointer precision, DPI mismatch) the
-probe reports it, since acceleration would break the 1:1 assumption.
+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.
 
 ## Develop
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebind.gg/mcp-server",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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": {

package/src/coords.ts

@@ -28,6 +28,13 @@ export function mapToScreen(shot: ShotMapping, ix: number, iy: number): Point {
   };
 }
 
+export function mapToImage(shot: ShotMapping, sx: number, sy: number): Point {
+  return {
+    x: Math.round((sx - shot.originX) * shot.scale),
+    y: Math.round((sy - shot.originY) * shot.scale),
+  };
+}
+
 export function inImageBounds(
   shot: ShotMapping,
   ix: number,

package/src/index.ts

@@ -12,8 +12,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { RebindRemote } from "@rebind.gg/client-ts";
 import { z } from "zod";
+import { mapToImage } from "./coords.ts";
 import { renderScreenshot } from "./image.ts";
-import { Session } from "./session.ts";
+import { CLICK_EPS_PX, Session } from "./session.ts";
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
@@ -52,7 +53,7 @@ async function main() {
 
   const session = new Session(client);
 
-  const server = new McpServer({ name: "rebind", version: "0.1.2" });
+  const server = new McpServer({ name: "rebind", version: "0.1.5" });
 
   // 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.
@@ -69,17 +70,28 @@ async function main() {
       // telemetry must never break a tool call
     }
   };
+  // one physical cursor and keyboard: tool calls must never overlap. Models
+  // routinely emit parallel calls in a single turn (two move_mouse at once)
+  // and the MCP SDK runs handlers concurrently; interleaved HID deltas and
+  // cursor readbacks make every overlapping move land nowhere. Chain all
+  // handlers through a single queue.
+  let chain: Promise<unknown> = Promise.resolve();
   const register = (name: string, config: object, handler: (args: any) => Promise<any>) => {
-    server.registerTool(name, config as any, async (args: any) => {
-      const t0 = performance.now();
-      try {
-        const result = await handler(args);
-        logCall(name, true, t0);
-        return result;
-      } catch (e) {
-        logCall(name, false, t0, String(e));
-        throw e;
-      }
+    server.registerTool(name, config as any, (args: any) => {
+      const run = async () => {
+        const t0 = performance.now();
+        try {
+          const result = await handler(args);
+          logCall(name, true, t0);
+          return result;
+        } catch (e) {
+          logCall(name, false, t0, String(e));
+          throw e;
+        }
+      };
+      const p = chain.then(run, run);
+      chain = p.catch(() => {});
+      return p;
     });
   };
 
@@ -89,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()
@@ -212,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()
@@ -276,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"),
@@ -287,10 +302,13 @@ async function main() {
     async ({ x, y, button, double }) => {
       const target = session.mapImagePoint(x, y);
       const r = await session.verifiedClick(target.x, target.y, button, double);
+      // report in the same image space the model emits — mixing in raw screen
+      // coordinates sends smaller models into ad-hoc rescaling math
+      const at = mapToImage(session.lastShot!, r.landed.x, r.landed.y);
       return text(
         r.ok
-          ? `clicked ${button}${double ? " (double)" : ""} at screen (${r.landed.x}, ${r.landed.y})${r.corrected ? " after one correction" : ""}`
-          : `WARNING: cursor landed at (${r.landed.x}, ${r.landed.y}) instead of (${target.x}, ${target.y}) — the click may have missed. Take a screenshot to verify.`,
+          ? `clicked ${button}${double ? " (double)" : ""} at image (${at.x}, ${at.y})${r.corrected ? " after one correction" : ""}`
+          : `WARNING: cursor landed at image (${at.x}, ${at.y}) instead of (${x}, ${y}) — the click may have missed. Take a screenshot to verify.`,
       );
     },
   );
@@ -299,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"),
@@ -308,14 +327,23 @@ async function main() {
     async ({ x, y }) => {
       const target = session.mapImagePoint(x, y);
       const landed = await session.moveTo(target.x, target.y);
-      return text(`cursor at screen (${landed.x}, ${landed.y})`);
+      const at = mapToImage(session.lastShot!, landed.x, landed.y);
+      const missed =
+        Math.hypot(landed.x - target.x, landed.y - target.y) > CLICK_EPS_PX;
+      return text(
+        missed
+          ? `WARNING: cursor stopped at image (${at.x}, ${at.y}) instead of (${x}, ${y}) — take a fresh screenshot and retry`
+          : `cursor at image (${at.x}, ${at.y})`,
+      );
     },
   );
 
   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 }) => {
@@ -331,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 }) => {
@@ -345,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 }) => {
@@ -375,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`,
+      );
     },
   );
 
@@ -423,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
@@ -439,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(): ()