@rebind.gg/mcp-server 0.2.2 → 0.2.4

package/package.json

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

@@ -266,6 +266,17 @@ 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.
@@ -300,9 +311,7 @@ async function buildInstructions(
   // 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
@@ -1146,10 +1155,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/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,399 @@ 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?,
+}
+
+-- 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) -> (),
+  },
+}
+
+-- v1 names
+-- The names every Rebind version accepts. They keep working.
+
 -- global functions
 
 declare function Run(fn: () -> ()): TaskHandle
@@ -284,23 +864,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 +885,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 +1006,6 @@ declare JSON: {
 
 -- process namespace
 
-export type ProcessEntry = {
-  pid: number,
-  name: string,
-}
-
 declare Process: {
   Exists: (name: string) -> number?,
   List: (name: string?) -> { ProcessEntry },
@@ -470,52 +1014,7 @@ 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: {
   GetPixelColor: (x: number?, y: number?) -> string,
@@ -572,11 +1071,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,
@@ -587,7 +1081,7 @@ declare App: {
   Quit: (name: string) -> (),
 }
 
--- net namespace
+-- net namespace (permission: net, or net:<host> for the client calls and WSConnect)
 
 declare Net: {
   Get: (url: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
@@ -640,20 +1134,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,
@@ -664,22 +1144,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: {
@@ -690,7 +1154,7 @@ declare Dialog: {
   SaveFile: (options: DialogFileOptions?) -> string?,
 }
 
--- clipboard namespace
+-- clipboard namespace (limited by clipboard:read, clipboard:write, clipboard:none)
 
 declare Clipboard: {
   Get: () -> string?,
@@ -706,13 +1170,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?,
@@ -776,27 +1233,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.