@rebind.gg/mcp-server 0.2.3 → 0.3.0

package/README.md

@@ -5,7 +5,9 @@ Stdio MCP server that turns [Rebind](https://rebind.gg) into a computer-use tool
 **Requirements**
 
 - [Bun](https://bun.sh) >= 1.1 (the server runs via `bunx`)
-- The [Rebind app](https://rebind.gg/download) running the free [Remote Control](https://www.rebind.gg/marketplace/script_AAHteeDcYPGOT7GfXZ_OK) package (`rebind install @rebind/remote-control`)
+- The [Rebind app](https://rebind.gg/download) running the free [Remote Control](https://www.rebind.gg/marketplace/script_AAHteeDcYPGOT7GfXZ_OK) package (`rebind install @rebind/remote-control --allow`)
+
+The first time the server sends a command, Remote Control asks on that computer whether to allow **Rebind MCP server**. Allow it once; the name is remembered. Tool calls fail with `awaiting_approval` until you answer. Remote Control accepts connections from its own computer only unless **Local only** is turned off in its Options, which an agent on another computer or inside WSL needs. `run_lua`, `focus_window`, `position_window` and `read_page` also need **Allow custom Luau** turned on there; the server reads that setting at startup.
 
 ## Install
 
@@ -41,7 +43,7 @@ Any MCP client takes the stdio block directly:
 bunx @rebind.gg/mcp-server --selftest
 ```
 
-Connects, takes a capture, and reports the display — the fastest way to catch the #1 first-run failure (relay not loaded).
+Connects, waits up to a minute for the approval prompt on a first run, takes a capture, and reports the display. It is the fastest way to catch the #1 first-run failure (relay not loaded).
 
 ## Tools
 
@@ -55,7 +57,7 @@ Connects, takes a capture, and reports the display — the fastest way to catch
 | `type` | Type text into the focused element. |
 | `key` | Press a key or combo, e.g. `Enter`, `LCtrl+L`, `LAlt+Tab`. |
 | `scroll` | Scroll at the cursor. Positive scrolls down, negative up. `unit` is `wheel` (default, fine wheel clicks) or `page` (one PageDown or PageUp per unit, capped at 10). |
-| `read_page` | Extract the focused browser's current page as structured text (URL, forms, interactive elements, plain text) via an address-bar bookmarklet; the full dump, including cleaned HTML, lands in the clipboard. The result is read back through AppleScript (`URL of active tab of front window`), so the tool is registered only when the relay host is macOS, and the front browser must answer that query. Safari is detected but blocks the bookmarklet path. |
+| `read_page` | Extract the focused browser's current page as structured text (URL, forms, interactive elements, plain text) via an address-bar bookmarklet; the full dump, including cleaned HTML, lands in the clipboard. The result is read back through AppleScript (`URL of active tab of front window`), so the tool is registered only when the relay host is macOS and **Allow custom Luau** is on, and the front browser must answer that query. Safari is detected but blocks the bookmarklet path. |
 | `meditate` | Research a problem page until a reasoning model has the data to solve it: fetches the URL directly, pulls the script bundles behind a JS shell so its API endpoints are visible, fetches those endpoints and assets, and reads the live page with vision. The browser steps (rendering a JS shell, same-origin fetches through the page, and the vision pass) need a macOS relay; elsewhere it reads pages over HTTP only. Returns a markdown dossier plus JSON `{error, problem, requirements, plan, submittable, form, live_captcha_hint, confidence, sources, assets, pending_fetch, notes, cost_usd}`. `error` is non-null when no problem could be identified or the page could not be read; partial data is still returned. Gated behind `REBIND_ALLOW_DELEGATION=1` (spends OpenRouter credits). See the pipeline below. |
 | `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`. |
@@ -84,7 +86,11 @@ Connects, takes a capture, and reports the display — the fastest way to catch
 
 **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.
 
-**Machine-aware orientation.** At startup the server probes the connected machine through the relay (OS, shortcut modifier, available shell tools, installed apps) and serves it as the MCP `instructions` block, along with a policy: prefer `run_lua` for deterministic work, keyboard over mouse, and screenshots last. The full Luau SDK type definitions are embedded inline so the model never has to guess `run_lua` APIs (including the coroutine-safe HID path — `HID.Down`/`Up`/`MoveTo`/`Combo` work in a one-shot chunk, `HID.Press` does not). The OS is read from the relay, not `process.platform`, so the guidance is correct even when the server and the relay run on different machines.
+**Machine-aware orientation.** At startup the server reads the OS from Remote Control's `hello` banner and, when custom Luau is allowed, probes the connected machine through the relay (available shell tools, installed apps) and serves it as the MCP `instructions` block, along with a policy: prefer `run_lua` for deterministic work, keyboard over mouse, and screenshots last. The full Luau SDK type definitions are embedded inline so the model never has to guess `run_lua` APIs (including the coroutine-safe HID path: `HID.Down`/`Up`/`MoveTo`/`Combo` work in a one-shot chunk, `HID.Press` does not). The OS is read from the relay, not `process.platform`, so the guidance is correct even when the server and the relay run on different machines.
+
+## Save what worked
+
+When the user wants a working sequence kept, the server's instructions tell the agent to save it as a Rebind script that runs with no agent: `rebind init <dir>`, the sequence in `main.luau` bound to a key, `[runtime] permissions` in `rebind.toml`, then `rebind check <dir>`, `rebind pack <dir>`, `rebind install <name>.rbp --allow` (`--force` to replace) and `rebind script start packages/<name>/main.luau`, on the computer running Rebind.
 
 ## Solve pipeline
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebind.gg/mcp-server",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "MCP server exposing Rebind as computer-use tools: screenshot, verified click, type, key, scroll, and window control over the Remote Control protocol.",
   "type": "module",
   "bin": {

package/src/index.ts

@@ -10,7 +10,7 @@ import { appendFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { RebindRemote } from "@rebind.gg/client-ts";
+import { RebindRemote, ServerError } from "@rebind.gg/client-ts";
 import { z } from "zod";
 import pkg from "../package.json";
 import { mapToImage } from "./coords.ts";
@@ -29,6 +29,7 @@ import {
   PROBE_CLIS_CMD,
   probeAppsCmd,
   RUN_LUA_DESC,
+  SAVE_WORK_DOCTRINE,
   toolPriority,
 } from "./prompts.ts";
 import { CLICK_EPS_PX, Session } from "./session.ts";
@@ -266,16 +267,32 @@ function assetsBlock(
     .join("\n\n");
 }
 
+// The SDK as run_lua scripts see it: the typedef without its rb block, so the
+// model writes the v1 names every relay version accepts (rb needs 3.9.0).
+// src/rebind.d.luau is a byte-identical copy of packages/lua-sdk/types/
+// rebind.d.luau shipped in the package; tests/lua-docs-sync.test.ts guards it.
+async function v1Sdk(): Promise<string> {
+  const typedef = await Bun.file(
+    new URL("./rebind.d.luau", import.meta.url),
+  ).text();
+  return typedef.replace(/^-- rb\n[\s\S]*?(?=^-- v1 names\n)/m, "");
+}
+
 // Server-level orientation (MCP `instructions`), built at startup. Every fact
 // is probed THROUGH the relay connection — process.platform is the wrong
 // signal because this process may run on a different machine than the relay.
 // Probes are best-effort: a locked-down remote (no exec permission) just
 // yields a shorter card. Machine facts and general technique only.
-// The probed OS is returned alongside: tools that pick a shortcut modifier
+// The OS comes from the hello banner when the server reports it (Remote
+// Control 0.3.0+), so it is right even with lua.exec off; older servers fall
+// back to a uname probe. When the banner says lua.exec is off, the probes and
+// read_page (both built on lua.exec) are skipped.
+// The OS is returned alongside: tools that pick a shortcut modifier
 // (read_page) need it, and re-probing would be a second relay round-trip.
 async function buildInstructions(
   client: RebindRemote,
-): Promise<{ instructions: string; os: OS }> {
+  hello: Hello,
+): Promise<{ instructions: string; os: OS; hasLua: boolean }> {
   const sh = async (cmd: string): Promise<string> => {
     try {
       const r = await client.luaExec(
@@ -286,23 +303,27 @@ async function buildInstructions(
       return "";
     }
   };
-  const uname = await sh("uname");
-  const os: OS = /darwin/i.test(uname)
-    ? "macOS"
-    : /linux/i.test(uname)
-      ? "Linux"
-      : "Windows";
-  const clis = os === "Windows" ? "" : await sh(PROBE_CLIS_CMD);
-  const apps = os === "Windows" ? "" : await sh(probeAppsCmd(os));
+  const hasLua = hello.gates?.lua !== false;
+  const os: OS =
+    HELLO_OS[hello.platform ?? ""] ??
+    (await (async () => {
+      const uname = hasLua ? await sh("uname") : "";
+      return /darwin/i.test(uname)
+        ? "macOS"
+        : /linux/i.test(uname)
+          ? "Linux"
+          : "Windows";
+    })());
+  const probe = hasLua && os !== "Windows";
+  const clis = probe ? await sh(PROBE_CLIS_CMD) : "";
+  const apps = probe ? await sh(probeAppsCmd(os)) : "";
   // Embed the full Luau SDK inline so the model never has to guess run_lua APIs
   // or make a lua_docs round-trip. It carries the coroutine-safety notes that
   // matter for HID: HID.Press sleeps and is coroutine-only, but HID.Down/Up/
   // MoveTo/Combo are synchronous and DO work in a one-shot chunk — so a mouse
   // click (e.g. ticking a checkbox) is scriptable as
   // `HID.MoveTo(x,y); HID.Down("Mouse1"); HID.Up("Mouse1")`.
-  const sdk = await Bun.file(
-    new URL("./rebind.d.luau", import.meta.url),
-  ).text();
+  const sdk = await v1Sdk();
   const instructions = [
     `You control a real ${os} computer through Rebind. Keyboard shortcuts use ${modifierNote(os)}.`,
     clis
@@ -311,8 +332,9 @@ async function buildInstructions(
     apps
       ? `GUI applications installed (open via ${openAppHow(os)}): ${apps}`
       : "",
-    `Work in as few steps as possible. ${DETERMINISTIC_WORK_DOCTRINE}`,
-    toolPriority(true),
+    `Work in as few steps as possible.${hasLua ? ` ${DETERMINISTIC_WORK_DOCTRINE}` : ""}`,
+    SAVE_WORK_DOCTRINE,
+    toolPriority(hasLua),
     BATCHING_DOCTRINE,
     "When you do need to see the screen, prefer screenshot_window over a full-display screenshot — a window shot costs roughly a quarter of the image tokens. Every screenshot stays in your context for the rest of the session, so each one you take keeps costing you on every later turn: verify with values (clipboard, file contents, run_lua reads) where possible.",
     guiTips(os),
@@ -321,14 +343,34 @@ async function buildInstructions(
   ]
     .filter(Boolean)
     .join("\n");
-  return { instructions, os };
+  return { instructions, os, hasLua };
 }
 
+/** the fields of the Remote Control hello banner this server reads */
+type Hello = { platform?: string; gates?: { lua?: boolean } };
+
+const HELLO_OS: Record<string, OS> = {
+  macos: "macOS",
+  linux: "Linux",
+  windows: "Windows",
+};
+
+/** the name Remote Control shows in its approval prompt and remembers */
+const APP_NAME = "Rebind MCP server";
+
 async function main() {
   const url = process.env.REBIND_URL ?? "ws://127.0.0.1:19561";
-  const client = new RebindRemote(url, {
+  // name this client on every connect, reconnects included: Remote Control
+  // approves programs by the name they declare in hello. setState fires before
+  // connect() resolves, so the hello goes out ahead of any tool call.
+  let hello: Promise<Hello> = Promise.resolve({});
+  const client: RebindRemote = new RebindRemote(url, {
     token: process.env.REBIND_TOKEN ?? "",
     timeoutMs: 15000,
+    onStateChange: (s) => {
+      if (s !== "connected") return;
+      hello = client.call<Hello>("hello", { app: APP_NAME }).catch(() => ({}));
+    },
   });
 
   // --selftest: verify the relay is reachable and capturing, then exit. Used by
@@ -337,15 +379,41 @@ async function main() {
   if (process.argv.includes("--selftest")) {
     try {
       await client.connect();
-      const cap = await client.screenCapture({});
+      await hello;
+      // a first connection waits on the approval prompt in Remote Control:
+      // retry for up to a minute while the person decides.
+      const deadline = Date.now() + 60_000;
+      let cap: Awaited<ReturnType<RebindRemote["screenCapture"]>>;
+      for (;;) {
+        try {
+          cap = await client.screenCapture({});
+          break;
+        } catch (e) {
+          const waiting =
+            e instanceof ServerError && e.code === "awaiting_approval";
+          if (!waiting || Date.now() + 2000 > deadline) throw e;
+          console.error(
+            `selftest: allow "${APP_NAME}" in the Remote Control prompt on that computer...`,
+          );
+          await sleep(2000);
+        }
+      }
       console.error(
         `selftest OK: relay ${url}, display ${cap.display.index} ${cap.display.width}x${cap.display.height}`,
       );
       process.exit(0);
     } catch (e) {
+      if (e instanceof ServerError) {
+        console.error(
+          e.code === "awaiting_approval" || e.code === "not_approved"
+            ? `selftest FAILED: "${APP_NAME}" was not allowed in Remote Control's prompt on ${url}. (${e.message})`
+            : `selftest FAILED: Remote Control on ${url} refused the capture. (${e.message})`,
+        );
+        process.exit(1);
+      }
       console.error(
         `selftest FAILED: Rebind relay not reachable on ${url}.\n` +
-          `Start Rebind and the Remote Control package (rebind install @rebind/remote-control).\n(${e})`,
+          `Start Rebind and the Remote Control package (rebind install @rebind/remote-control --allow).\n(${e})`,
       );
       process.exit(1);
     }
@@ -355,7 +423,10 @@ async function main() {
 
   const session = new Session(client);
 
-  const { instructions, os } = await buildInstructions(client);
+  const { instructions, os, hasLua } = await buildInstructions(
+    client,
+    await hello,
+  );
   const server = new McpServer(
     { name: "rebind", version: pkg.version },
     { instructions },
@@ -1071,9 +1142,9 @@ return { ok = Window.IsActive(h), name = name }
   );
 
   // read_page finds the front app through App.Front and reads its result back
-  // through AppleScript (tabUrl): both exist only on a macOS relay. A failed
-  // OS probe reads as "Windows", so this never offers the tool where it fails.
-  if (os === "macOS") {
+  // through AppleScript (tabUrl), both over lua.exec: offered only on a macOS
+  // relay with lua.exec on, so never where it fails.
+  if (os === "macOS" && hasLua) {
     register(
       "read_page",
       {
@@ -1146,10 +1217,7 @@ return { ok = Window.IsActive(h), name = name }
     {
       description: LUA_DOCS_DESC,
     },
-    // 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()),
+    async () => text(await v1Sdk()),
   );
 
   // Server-side subagents. Gated: a stock install ships without them. They make

package/src/prompts.ts

@@ -69,6 +69,10 @@ export function guiTips(os: OS): string {
 export const DETERMINISTIC_WORK_DOCTRINE =
   "run_lua is your PRIMARY tool — reach for it FIRST and use it aggressively. It exposes the ENTIRE machine SDK (every namespace below), so almost anything a task needs — file operations, text processing, arithmetic, clipboard, launching and positioning apps, shell commands, reading the screen — is ONE run_lua call, never a click loop. Do not operate calculators, browsers, or file managers through the GUI when a script can do the work. Fall back to screenshot/click ONLY for state that exists purely on screen and cannot be scripted.";
 
+/** MCP server only (the bench keeps its own prompt): keep what worked. */
+export const SAVE_WORK_DOCTRINE =
+  "When a sequence works and the user wants to keep it, save it as a Rebind script so it runs again with no agent and no tokens. On the computer running Rebind: `rebind init <dir>` scaffolds rebind.toml and main.luau; put the sequence in main.luau bound to a key (Bind or OnDown; hooks never fire inside run_lua, they do in an installed script); add `[runtime] permissions = [...]` to rebind.toml listing only what it uses; then run `rebind check <dir>`, `rebind pack <dir>` (writes <name>.rbp in the current directory), `rebind install <name>.rbp --allow` (it prints what the package asks for; add --force to replace an earlier install) and `rebind script start packages/<name>/main.luau`. Tell the user which key runs it, and that it runs until Rebind restarts and can be started again from Rebind's scripts list.";
+
 // --- tool descriptions (shared only where the underlying behavior is identical
 // across both surfaces: run_lua, lua_docs, and key all hit the same relay) ---
 

package/src/rebind.d.luau

@@ -1,18 +1,28 @@
--- 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"] }
+-- Rebind SDK type definitions for the Luau language server: autocomplete,
+-- hover docs and type checking for every SDK function.
+-- Reference this file in your .luaurc: { "languageMode": "strict", "paths": ["types"] }
+--
+-- The rb names need Rebind 3.9.0 or later; the v1 names work on every
+-- version.
 
--- handle types
+-- handle types. A handle answers to its v1 method names on every version,
+-- and to their snake_case forms from Rebind 3.9.0.
 
 export type TaskHandle = {
   Cancel: (self: TaskHandle) -> (),
   IsRunning: (self: TaskHandle) -> boolean,
+  stop: (self: TaskHandle) -> (),
+  is_running: (self: TaskHandle) -> boolean,
 }
 
 export type TimerHandle = {
   Cancel: (self: TimerHandle) -> (),
   Pause: (self: TimerHandle) -> (),
   Resume: (self: TimerHandle) -> (),
+  stop: (self: TimerHandle) -> (),
+  pause: (self: TimerHandle) -> (),
+  resume: (self: TimerHandle) -> (),
+  is_running: (self: TimerHandle) -> boolean,
 }
 
 export type MacroHandle = {
@@ -21,18 +31,34 @@ export type MacroHandle = {
   Resume: (self: MacroHandle) -> (),
   IsPlaying: (self: MacroHandle) -> boolean,
   GetProgress: (self: MacroHandle) -> number,
+  -- coroutine-only: waits until the macro finishes
+  Wait: (self: MacroHandle) -> (),
+  stop: (self: MacroHandle) -> (),
+  pause: (self: MacroHandle) -> (),
+  resume: (self: MacroHandle) -> (),
+  is_playing: (self: MacroHandle) -> boolean,
+  get_progress: (self: MacroHandle) -> number,
+  -- coroutine-only: waits until the macro finishes
+  wait: (self: MacroHandle) -> (),
 }
 
 export type BindHandle = {
   unbind: (self: BindHandle) -> (),
+  stop: (self: BindHandle) -> (),
   disable: (self: BindHandle) -> (),
   enable: (self: BindHandle) -> (),
   enabled: boolean,
 }
 
+-- returned by rb.on (Rebind 3.9.0 and later); stop removes the handler
+export type EventHandle = {
+  stop: (self: EventHandle) -> (),
+}
+
 export type ServerHandle = {
   port: number,
   Stop: (self: ServerHandle) -> (),
+  stop: (self: ServerHandle) -> (),
 }
 
 -- UDP: socket handle returned by Net.UDPListen. SendTo sends from the bound
@@ -41,6 +67,8 @@ export type UdpHandle = {
   port: number,
   SendTo: (self: UdpHandle, ip: string, port: number, bytes: string) -> boolean,
   Stop: (self: UdpHandle) -> (),
+  send_to: (self: UdpHandle, ip: string, port: number, bytes: string) -> boolean,
+  stop: (self: UdpHandle) -> (),
 }
 
 -- WebSocket: server-side per-connection handle passed to OnConnect/OnMessage/OnClose.
@@ -50,6 +78,9 @@ export type WsClient = {
   Send: (self: WsClient, text: string) -> (),
   SendBinary: (self: WsClient, bytes: string) -> (),
   Close: (self: WsClient) -> (),
+  send: (self: WsClient, text: string) -> (),
+  send_binary: (self: WsClient, bytes: string) -> (),
+  close: (self: WsClient) -> (),
 }
 
 -- WebSocket: server handle returned by Net.WSListen.
@@ -59,6 +90,10 @@ export type WsServerHandle = {
   BroadcastBinary: (self: WsServerHandle, bytes: string) -> (),
   ClientCount: (self: WsServerHandle) -> number,
   Stop: (self: WsServerHandle) -> (),
+  broadcast: (self: WsServerHandle, text: string) -> (),
+  broadcast_binary: (self: WsServerHandle, bytes: string) -> (),
+  client_count: (self: WsServerHandle) -> number,
+  stop: (self: WsServerHandle) -> (),
 }
 
 -- WebSocket: outbound-connection handle returned by Net.WSConnect.
@@ -66,21 +101,32 @@ export type WsConnectHandle = {
   Send: (self: WsConnectHandle, text: string) -> (),
   SendBinary: (self: WsConnectHandle, bytes: string) -> (),
   Close: (self: WsConnectHandle) -> (),
+  send: (self: WsConnectHandle, text: string) -> (),
+  send_binary: (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.
+-- From Rebind 3.9.0 each handler is also read under its snake_case name.
 export type WsListenHandlers = {
   OnConnect: ((client: WsClient) -> ())?,
   OnMessage: ((client: WsClient, payload: string, isBinary: boolean) -> ())?,
   OnClose: ((client: WsClient) -> ())?,
+  on_connect: ((client: WsClient) -> ())?,
+  on_message: ((client: WsClient, payload: string, is_binary: boolean) -> ())?,
+  on_close: ((client: WsClient) -> ())?,
 }
 
 -- WebSocket: client event-handler table passed to Net.WSConnect.
+-- From Rebind 3.9.0 each handler is also read under its snake_case name.
 export type WsConnectHandlers = {
   OnOpen: (() -> ())?,
   OnMessage: ((payload: string, isBinary: boolean) -> ())?,
   OnClose: (() -> ())?,
+  on_open: (() -> ())?,
+  on_message: ((payload: string, is_binary: boolean) -> ())?,
+  on_close: (() -> ())?,
 }
 
 export type PipeHandle = {
@@ -90,6 +136,24 @@ export type PipeHandle = {
   Read: (self: PipeHandle) -> string?,
   Write: (self: PipeHandle, data: string) -> (),
   Close: (self: PipeHandle) -> (),
+  read: (self: PipeHandle) -> string?,
+  write: (self: PipeHandle, data: string) -> (),
+  close: (self: PipeHandle) -> (),
+}
+
+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,
+  stop: (self: SoundHandle) -> (),
+  pause: (self: SoundHandle) -> (),
+  resume: (self: SoundHandle) -> (),
+  is_playing: (self: SoundHandle) -> boolean,
+  set_volume: (self: SoundHandle, vol: number) -> (),
+  get_volume: (self: SoundHandle) -> number,
 }
 
 -- data types
@@ -178,6 +242,122 @@ export type HttpRequestOptions = {
   timeout: number?,
 }
 
+export type ExecOptions = {
+  -- milliseconds; default 5000. The process is killed on expiry and Exec errors.
+  timeout: number?,
+  -- working directory for the command; default: the host process's cwd.
+  cwd: string?,
+}
+
+export type ExecResult = {
+  exit: number,
+  stdout: string,
+  stderr: string,
+}
+
+export type ExecDetachedOptions = {
+  cwd: string?,
+}
+
+-- a joypad state; every field is optional and defaults to neutral. buttons
+-- lists pressed buttons 1-32, hat is 0 (up) to 7 clockwise (nil = centered),
+-- x/y/z/rz are -1..1 (0 = center), slider and dial are 0..1.
+export type JoypadState = {
+  buttons: { number }?,
+  hat: number?,
+  x: number?,
+  y: number?,
+  z: number?,
+  rz: number?,
+  slider: number?,
+  dial: number?,
+}
+
+export type ProcessEntry = {
+  pid: number,
+  name: string,
+}
+
+export type PixelMatch = {
+  x: number,
+  y: number,
+}
+
+export type MonitorEntry = {
+  index: number,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  primary: boolean,
+}
+
+export type CaptureOptions = {
+  -- 1-based display index; default: the display under the cursor.
+  display: number?,
+  -- display-local logical coords; default: the whole display.
+  region: { x: number, y: number, w: number, h: number }?,
+  -- downscale so the long edge is at most this; default and 0: native.
+  max_edge: number?,
+}
+
+export type CaptureResult = {
+  image: string, -- base64 PNG
+  width: number,
+  height: number,
+  display: MonitorEntry,
+  cursor: { x: number, y: number },
+}
+
+export type FindImageOptions = {
+  display: number?,
+  region: { x: number, y: number, w: number, h: number }?,
+  -- 0.0 exact .. 1.0, per-channel fraction of 255 (same scale as SearchForColor).
+  tolerance: number?,
+  -- ratios to resample the needle by before scanning, tried in order; default { 1 }.
+  scales: { number }?,
+}
+
+export type ImageMatch = {
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+}
+
+export type AppInfo = {
+  name: string,
+  pid: number,
+}
+
+export type PlayOptions = {
+  volume: number?,
+  loop: boolean?,
+}
+
+export type DialogMessageOptions = {
+  title: string?,
+  level: string?,
+}
+
+export type DialogFileFilter = {
+  name: string,
+  extensions: { string },
+}
+
+export type DialogFileOptions = {
+  title: string?,
+  location: string?,
+  filters: { DialogFileFilter }?,
+}
+
+export type RegexMatch = {
+  match: string,
+  captures: { string },
+  start: number,
+  finish: number,
+}
+
 -- macro action types
 
 export type MacroMoveAction = {
@@ -186,6 +366,8 @@ export type MacroMoveAction = {
   delay: number,
 }
 
+-- from Rebind 3.9.0, holdMs and charDelay are also read as hold_ms and
+-- char_delay
 export type MacroExplicitAction = {
   action: string,
   code: string?,
@@ -197,12 +379,15 @@ export type MacroExplicitAction = {
   amount: number?,
   holdMs: number?,
   charDelay: number?,
+  hold_ms: number?,
+  char_delay: number?,
   delay: number,
 }
 
 export type MacroAction = MacroMoveAction | MacroExplicitAction
 
--- ui widget option types
+-- ui widget option types; from Rebind 3.9.0, showIf and maxLength are also
+-- read as show_if and max_length
 
 export type WidgetOpts = {
   label: string?,
@@ -210,6 +395,7 @@ export type WidgetOpts = {
   group: string?,
   tab: string?,
   showIf: string?,
+  show_if: string?,
 }
 
 export type ToggleOpts = WidgetOpts
@@ -228,6 +414,7 @@ export type SelectOpts = WidgetOpts
 export type TextOpts = WidgetOpts & {
   placeholder: string?,
   maxLength: number?,
+  max_length: number?,
 }
 
 export type ColorOpts = WidgetOpts
@@ -264,6 +451,453 @@ export type RebindInfo = {
   platform: string,
 }
 
+-- options of the rb calls that take one options table (Rebind 3.9.0 and later)
+
+export type RbHttpOptions = {
+  headers: { [string]: string }?,
+  timeout: number?,
+}
+
+export type RbPlayOptions = {
+  -- playback speed multiplier
+  speed: number?,
+  -- "parallel" (default, plays alongside running macros) | "replace"
+  -- (stops all running macros first)
+  mode: string?,
+}
+
+export type RbExecDetachedOptions = {
+  args: { string }?,
+  cwd: string?,
+}
+
+-- fields left out keep their current value
+export type RbWindowRect = {
+  x: number?,
+  y: number?,
+  width: number?,
+  height: number?,
+}
+
+export type RbBindOptions = {
+  -- false lets the key through to the system; default: the key is taken
+  swallow: boolean?,
+  -- checked on each press; false skips the bind for that press
+  when: ((device: InputDevice?) -> boolean)?,
+  -- runs when the key is released
+  release: ((device: InputDevice?) -> ())?,
+  -- nickname or id: the bind answers only to that device
+  device: string?,
+}
+
+-- rb.ai and rb.phone are Rebind Pro (a 7-day trial starts on first use).
+-- Each rb.ai call waits for the model, so call it inside rb.run; its cost
+-- counts against the monthly AI allowance. A script that declares
+-- permissions needs ai, or ai:decide, ai:find or ai:read. A window option
+-- names a window by title (or app name on macOS); the call reads the screen
+-- pixels inside that window's rectangle, through the screen: permission.
+
+export type AiDecideOptions = {
+  choices: { string },
+  -- send the display under the cursor (the target window under screen:target)
+  screen: boolean?,
+  -- send this window instead
+  window: string?,
+}
+
+export type AiFindOptions = {
+  -- look in this window; default: the display under the cursor
+  window: string?,
+}
+
+export type AiReadOptions = {
+  window: string?,
+  -- read only around this point (screen coordinates, such as rb.ai.find's)
+  at: AiPoint?,
+}
+
+-- screen coordinates, for rb.hid.move_to
+export type AiPoint = {
+  x: number,
+  y: number,
+}
+
+export type RbAi = {
+  -- picks one of opts.choices; returns it and the model's confidence (0 to 1)
+  decide: (question: string, opts: AiDecideOptions) -> (string, number),
+  -- the centre of what is described, or nil when it is not visible
+  find: (what: string, opts: AiFindOptions?) -> AiPoint?,
+  -- the text described, as it appears on screen
+  read: (what: string, opts: AiReadOptions?) -> string,
+}
+
+export type PhoneResult = {
+  delivered: boolean,
+  reason: string?,
+}
+
+export type RbPhone = {
+  -- no phone app yet: returns { delivered = false, reason = "no phone connected" }
+  notify: (text: string, title: string?) -> PhoneResult,
+}
+
+-- events for rb.on (Rebind 3.9.0 and later), with the arguments each
+-- handler receives. For down, up, move and scroll, a handler that returns
+-- false swallows the input.
+export type Event =
+  | "start" -- ()
+  | "stop" -- ()
+  | "focus" -- (window: WindowInfo)
+  | "blur" -- (window: WindowInfo)
+  | "tick" -- (dt_ms: number)
+  | "error" -- (message: string)
+  | "reload" -- ()
+  | "down" -- (key: string, device: InputDevice?)
+  | "up" -- (key: string, duration_ms: number, device: InputDevice?)
+  | "move" -- (dx: number, dy: number, device: InputDevice?) hardware mode only
+  | "scroll" -- (delta: number, device: InputDevice?)
+  | "scroll_h" -- (delta: number)
+  | "input_down" -- (key: string, device: InputDevice?)
+  | "input_up" -- (key: string, duration_ms: number, device: InputDevice?)
+  | "input_move" -- (dx: number, dy: number, device: InputDevice?)
+  | "input_scroll" -- (delta: number, device: InputDevice?)
+
+-- valid key names for input events and binds:
+--
+-- 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:
+-- 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.
+
+-- rb
+-- The scripting surface, for scripts that declare min_sdk=3.9.0 or later.
+-- Every name is the snake_case of a v1 name (HID.MoveTo is rb.hid.move_to).
+-- Hooks are rb.on(event, fn) and key names passed to rb ignore case.
+
+declare rb: {
+  -- runtime identity: script name, versions, platform
+  info: RebindInfo,
+  -- runs fn as a coroutine, where rb.sleep and other coroutine-only calls work
+  run: (fn: () -> ()) -> TaskHandle,
+  -- coroutine-only: call inside rb.run
+  sleep: (ms: number) -> (),
+  after: (ms: number, fn: () -> ()) -> TaskHandle,
+  -- wraps fn so it runs on the coroutine scheduler; when auto-spawned the call
+  -- returns false instead of fn's results.
+  async: (fn: (...any) -> ...any) -> (...any) -> ...any,
+  -- adds a handler for an event; handlers run in the order they were added.
+  -- returns a handle whose stop removes the handler.
+  on: (event: Event, fn: (...any) -> boolean?) -> EventHandle,
+  -- rb.bind(key, fn, options) takes the key unless options.swallow is false.
+  -- the callback's return value is ignored.
+  bind: typeof(setmetatable({} :: {
+    toggle: (key: string, ui_id: string) -> BindHandle,
+    remap: (from: string, to: string) -> BindHandle,
+  }, {} :: {
+    __call: (self: any, key: string, fn: ((device: InputDevice?) -> ...any)?, options: RbBindOptions?) -> BindHandle,
+  })),
+  -- each level takes any number of values, joined like print
+  log: {
+    info: (...any) -> (),
+    warn: (...any) -> (),
+    error: (...any) -> (),
+    debug: (...any) -> (),
+  },
+  system: {
+    time: () -> number,
+    mouse: () -> (number, number),
+    screen: () -> (number, number),
+    window: () -> WindowInfo,
+    -- runs cmd through the shell (sh -c / cmd.exe), output capped at 64KB per
+    -- stream. Requires the 'exec' permission. Inside rb.run it runs off the
+    -- tick thread; elsewhere it blocks the tick thread and warns once.
+    exec: (cmd: string, options: ExecOptions?) -> ExecResult,
+    -- fire-and-forget spawn (no shell, argv array); returns the pid.
+    exec_detached: (cmd: string, options: RbExecDetachedOptions?) -> number,
+    -- types text through the host OS (Unicode aware), never through the HID
+    -- transport. raises when the OS refuses the injection.
+    type_text: (text: string) -> (),
+  },
+  hid: {
+    down: (code: string) -> (),
+    up: (code: string) -> (),
+    -- coroutine-only (sleeps for hold_ms): call inside rb.run. From a plain
+    -- chunk use down and up, or combo.
+    press: (code: string, hold_ms: number?) -> (),
+    -- fires a chord in one synchronous call (press left to right, release
+    -- right to left). modifier tokens accept macOS aliases: "cmd",
+    -- "opt"/"option", plus "ctrl"/"shift"/"alt"/"win".
+    combo: (code: string) -> (),
+    -- instant whole-string insertion; typewriter types one character at a
+    -- time and is coroutine-only.
+    type: (text: string) -> (),
+    typewriter: (text: string, delay_ms: number?) -> (),
+    move: (dx: number, dy: number) -> (),
+    move_to: (x: number, y: number) -> (),
+    scroll: (amount: number) -> (),
+    set_mouse_mode: (mode: string) -> (),
+    get_mouse_mode: () -> string,
+    -- keyboard HID usage for a key name, or nil (media keys return nil). down,
+    -- up, press and combo also accept "usage:N" (decimal or 0x hex, 0x04-0xE7).
+    usage: (name: string) -> number?,
+    -- sets the whole joypad state (last write wins across scripts). Needs a
+    -- Rebind Link whose USB profile has a joypad; raises otherwise.
+    joypad: (state: JoypadState?) -> (),
+    -- back to neutral; the relay also does this when a script stops or errors
+    joypad_reset: () -> (),
+  },
+  input: {
+    is_down: (code: string) -> boolean,
+    duration: (code: string) -> number,
+    keys: () -> { string },
+    mouse_pos: () -> MousePos,
+    modifiers: () -> ModifierState,
+  },
+  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) -> (),
+    get_all: () -> { [string]: any },
+    get_schema: () -> { any },
+    notify: (text: string, variant: string?) -> (),
+  },
+  timer: {
+    after: (ms: number, callback: () -> ()) -> TimerHandle,
+    every: (ms: number, callback: () -> ()) -> TimerHandle,
+    stop_all: () -> (),
+  },
+  macro: {
+    play: (macro: { MacroAction }, options: RbPlayOptions?) -> MacroHandle,
+    stop_all: () -> (),
+    record: (options: RecordOpts?) -> (),
+    finish: () -> { MacroAction },
+    -- the saved-macro format: a `macro=true` modeline, then `return` of the
+    -- actions. require() of a saved macro returns the actions.
+    to_script: (macro: { MacroAction }, name: string) -> string,
+    stream: (macro: { MacroAction }) -> (),
+    abort: () -> (),
+  },
+  math: {
+    random: (min: number, max: number) -> number,
+    gaussian: (mean: number, std_dev: number) -> number,
+    scale: (macro: { MacroAction }, x_factor: number, y_factor: number) -> { MacroAction },
+    spline: (macro: { MacroAction }, tension: number) -> { MacroAction },
+    resample: (macro: { MacroAction }, interval_ms: number) -> { MacroAction },
+    time_comp: (macro: { MacroAction }, target_ms: number) -> { MacroAction },
+    -- mode: "linear" | anything else = positional curve (default).
+    interpolate: (macro: { MacroAction }, interval_ms: number, mode: string?) -> { MacroAction },
+  },
+  json: {
+    parse: (s: string) -> any,
+    stringify: (value: any) -> string,
+  },
+  process: {
+    exists: (name: string) -> number?,
+    list: (name: string?) -> { ProcessEntry },
+    kill: (pid: number) -> boolean,
+  },
+  -- pixel reads are limited by a screen:target or screen:none permission entry
+  screen: {
+    pixel_hex: (x: number?, y: number?) -> string,
+    -- reads the published frame. regions up to 200k physical pixels answer on
+    -- the calling thread; larger ones yield inside rb.run and are refused
+    -- outside it.
+    search_color: (region: { number }, color: string, tolerance: number?) -> PixelMatch?,
+    list: () -> { MonitorEntry },
+    -- yields inside rb.run; refused outside a coroutine.
+    capture: (options: CaptureOptions?) -> CaptureResult,
+    -- needle is a PNG path relative to the script directory. yields inside
+    -- rb.run; refused outside a coroutine.
+    find_image: (needle: string, options: FindImageOptions?) -> ImageMatch?,
+    -- usable desktop of the display containing the point (cursor when omitted).
+    -- Windows only; raises elsewhere.
+    work_area: (x: number?, y: number?) -> WindowPos,
+  },
+  window: {
+    find: (title: string) -> number?,
+    list: (title: string?) -> { WindowEntry },
+    get_title: (handle: number?) -> string,
+    get_class: (handle: number?) -> string,
+    get_pos: (handle: number?) -> WindowPos,
+    get_pid: (handle: number?) -> number,
+    activate: (handle: number) -> (),
+    move: (handle: number?, rect: RbWindowRect?) -> (),
+    set_always_on_top: (handle: number, enabled: boolean) -> (),
+    set_transparency: (handle: number, alpha: number) -> (),
+    set_title: (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?) -> (),
+    is_visible: (handle: number) -> boolean,
+    is_active: (handle: number?) -> boolean,
+    get_foreground: () -> number?,
+    from_point: (x: number, y: number) -> number?,
+    -- "minimized" | "maximized" | "normal". Windows only; raises elsewhere.
+    get_state: (handle: number?) -> string,
+    wait: (title: string, timeout: number?) -> number?,
+    wait_active: (title: string, timeout: number?) -> boolean,
+    wait_close: (title: string, timeout: number?) -> boolean,
+  },
+  -- application control. macOS matches app display names ignoring case;
+  -- Windows matches executable names (".exe" optional) and cannot hide;
+  -- Linux raises on every call.
+  app: {
+    front: () -> AppInfo?,
+    is_front: (name: string) -> boolean,
+    is_running: (name: string) -> boolean,
+    is_hidden: (name: string) -> boolean,
+    activate: (name: string) -> (),
+    hide: (name: string) -> (),
+    quit: (name: string) -> (),
+  },
+  -- permission: net, or net:<host> for the client calls and ws_connect
+  net: {
+    get: (url: string, options: RbHttpOptions?) -> HttpResponse,
+    post: (url: string, body: string, options: RbHttpOptions?) -> HttpResponse,
+    put: (url: string, body: string, options: RbHttpOptions?) -> HttpResponse,
+    patch: (url: string, body: string, options: RbHttpOptions?) -> HttpResponse,
+    delete: (url: string, options: RbHttpOptions?) -> HttpResponse,
+    head: (url: string, options: RbHttpOptions?) -> HttpResponse,
+    request: (options: HttpRequestOptions) -> HttpResponse,
+    listen: (port: number, handler: (request: HttpRequest) -> HttpResponseSpec | string) -> ServerHandle,
+    ws_listen: (port: number, handlers: WsListenHandlers) -> WsServerHandle,
+    ws_connect: (url: string, handlers: WsConnectHandlers) -> WsConnectHandle,
+    -- binds a UDP socket; handler receives each datagram's raw bytes and sender.
+    udp_listen: (bind_ip: string, port: number, handler: (data: string, ip: string, port: number) -> ()) -> UdpHandle,
+    -- this computer's IPv4 address on its default route, or nil when there is none.
+    local_ip: () -> string?,
+  },
+  pipe: {
+    open: (name: string, options: { size: number? }?) -> PipeHandle,
+  },
+  -- paths are relative to the script directory; absolute paths are rejected
+  file: {
+    read: (path: string) -> string,
+    read_bytes: (path: string) -> string,
+    write: (path: string, content: string) -> (),
+    append: (path: string, content: string) -> (),
+    exists: (path: string) -> boolean,
+    delete: (path: string) -> boolean,
+    -- nil path lists the script's own directory
+    list: (path: string?) -> { string },
+    mkdir: (path: string) -> boolean,
+    -- recursive; returns true even when the directory did not exist.
+    rmdir: (path: string) -> boolean,
+    copy: (src: string, dst: string) -> (),
+    move: (src: string, dst: string) -> (),
+    read_json: (path: string) -> any,
+    write_json: (path: string, value: any) -> (),
+    script_dir: () -> string,
+    size: (path: string) -> number,
+    time: (path: string) -> number,
+    is_dir: (path: string) -> boolean,
+    is_file: (path: string) -> boolean,
+  },
+  audio: {
+    beep: () -> (),
+    play: (path: string, options: PlayOptions?) -> SoundHandle,
+    stop_all: () -> (),
+    set_master_volume: (vol: number) -> (),
+    get_master_volume: () -> number,
+  },
+  -- every dialog call is coroutine-only: it yields until the dialog closes
+  -- and errors outside rb.run. the pickers return nil on cancel.
+  dialog: {
+    message: (text: string, options: DialogMessageOptions?) -> (),
+    confirm: (text: string, options: DialogMessageOptions?) -> boolean,
+    open_file: (options: DialogFileOptions?) -> string?,
+    open_dir: (options: DialogFileOptions?) -> string?,
+    save_file: (options: DialogFileOptions?) -> string?,
+  },
+  -- limited by clipboard:read, clipboard:write, clipboard:none
+  clipboard: {
+    get: () -> string?,
+    set: (text: string) -> (),
+  },
+  script: {
+    exit: (reason: string?) -> (),
+    reload: () -> (),
+  },
+  regex: {
+    is_match: (text: string, pattern: string) -> boolean,
+    find: (text: string, pattern: string) -> RegexMatch?,
+    find_all: (text: string, pattern: string) -> { RegexMatch },
+    replace: (text: string, pattern: string, replacement: string) -> string,
+    replace_all: (text: string, pattern: string, replacement: string) -> string,
+    split: (text: string, pattern: string) -> { string },
+  },
+  config: {
+    parse_toml: (text: string) -> { [string]: any },
+    to_toml: (value: { [string]: any }) -> string,
+    read_toml: (path: string) -> { [string]: any },
+    write_toml: (path: string, value: { [string]: any }) -> (),
+  },
+  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: {
+    base64: (data: string) -> string,
+    base64_decode: (str: string) -> string,
+    hex: (data: string) -> string,
+    hex_decode: (str: string) -> string,
+  },
+  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?,
+  },
+  -- Windows only
+  registry: {
+    read: (key_path: string, value_name: string) -> string | number,
+    write: (key_path: string, type: string, value_name: string, value: any) -> (),
+    delete_value: (key_path: string, value_name: string) -> (),
+    delete_key: (key_path: string) -> (),
+    create_key: (key_path: string) -> (),
+  },
+  -- Rebind Pro; require("@rebind/pro") returns rb
+  ai: RbAi,
+  phone: RbPhone,
+}
+
+-- v1 names
+-- The names every Rebind version accepts. They keep working.
+
 -- global functions
 
 declare function Run(fn: () -> ()): TaskHandle
@@ -284,23 +918,6 @@ declare _REBIND: RebindInfo
 
 -- system namespace
 
-export type ExecOptions = {
-  -- milliseconds; default 5000. The process is killed on expiry and Exec errors.
-  timeout: number?,
-  -- working directory for the command; default: the host process's cwd.
-  cwd: string?,
-}
-
-export type ExecResult = {
-  exit: number,
-  stdout: string,
-  stderr: string,
-}
-
-export type ExecDetachedOptions = {
-  cwd: string?,
-}
-
 declare System: {
   Time: () -> number,
   Mouse: () -> (number, number),
@@ -322,20 +939,6 @@ declare System: {
 
 -- hid namespace
 
--- a joypad state; every field is optional and defaults to neutral. buttons
--- lists pressed buttons 1-32, hat is 0 (up) to 7 clockwise (nil = centered),
--- x/y/z/rz are -1..1 (0 = center), slider and dial are 0..1.
-export type JoypadState = {
-  buttons: { number }?,
-  hat: number?,
-  x: number?,
-  y: number?,
-  z: number?,
-  rz: number?,
-  slider: number?,
-  dial: number?,
-}
-
 declare HID: {
   Down: (code: string) -> (),
   Up: (code: string) -> (),
@@ -457,11 +1060,6 @@ declare JSON: {
 
 -- process namespace
 
-export type ProcessEntry = {
-  pid: number,
-  name: string,
-}
-
 declare Process: {
   Exists: (name: string) -> number?,
   List: (name: string?) -> { ProcessEntry },
@@ -470,53 +1068,6 @@ declare Process: {
 
 -- screen namespace
 
-export type PixelMatch = {
-  x: number,
-  y: number,
-}
-
-export type MonitorEntry = {
-  index: number,
-  x: number,
-  y: number,
-  width: number,
-  height: number,
-  primary: boolean,
-}
-
-export type CaptureOptions = {
-  -- 1-based display index; default: the display under the cursor.
-  display: number?,
-  -- display-local logical coords; default: the whole display.
-  region: { x: number, y: number, w: number, h: number }?,
-  -- downscale so the long edge is at most this; default and 0: native.
-  max_edge: number?,
-}
-
-export type CaptureResult = {
-  image: string, -- base64 PNG
-  width: number,
-  height: number,
-  display: MonitorEntry,
-  cursor: { x: number, y: number },
-}
-
-export type FindImageOptions = {
-  display: number?,
-  region: { x: number, y: number, w: number, h: number }?,
-  -- 0.0 exact .. 1.0, per-channel fraction of 255 (same scale as SearchForColor).
-  tolerance: number?,
-  -- ratios to resample the needle by before scanning, tried in order; default { 1 }.
-  scales: { number }?,
-}
-
-export type ImageMatch = {
-  x: number,
-  y: number,
-  width: number,
-  height: number,
-}
-
 -- pixel reads are limited by a screen:target or screen:none permission entry
 
 declare Screen: {
@@ -544,7 +1095,7 @@ declare Window: {
   GetPos: (handle: number?) -> WindowPos,
   GetPID: (handle: number?) -> number,
   Activate: (handle: number) -> (),
-  Move: (handle: number, x: number?, y: number?, width: number?, height: 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) -> (),
@@ -574,11 +1125,6 @@ declare Window: {
 -- Activate focuses a running app and does not launch one; Quit closes its
 -- windows; Hide/IsHidden raise. Linux: every call raises.
 
-export type AppInfo = {
-  name: string,
-  pid: number,
-}
-
 declare App: {
   Front: () -> AppInfo?,
   IsFront: (name: string) -> boolean,
@@ -642,20 +1188,6 @@ declare File: {
 
 -- 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,
@@ -666,22 +1198,6 @@ declare Audio: {
 
 -- 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 }?,
-}
-
 -- every Dialog call is coroutine-only: it yields until the dialog closes and
 -- errors outside Run(). the file and folder pickers return nil on cancel.
 declare Dialog: {
@@ -708,13 +1224,6 @@ declare Script: {
 
 -- 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?,
@@ -778,27 +1287,6 @@ declare Registry: {
   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.