@rebind.gg/mcp-server 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebind.gg/mcp-server",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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": {
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@rebind.gg/client-ts": "0.3.0",
+    "@rebind.gg/client-ts": "0.3.3",
     "sharp": "^0.34.2",
     "zod": "^3.25.0"
   },

package/src/fetch-guard.ts

@@ -0,0 +1,55 @@
+// The meditate tool's check on model- and page-chosen URLs before they reach
+// relay-side curl (spliced into a shell command inside Lua long-bracket
+// quoting) or the user's browser.
+
+import { isIP } from "node:net";
+
+/** plain http(s), with nothing that could leave the shell or Lua quoting or
+ *  that curl reads as a glob ([] and {}); bracketed IPv6 literals stop here */
+const SAFE_URL = /^https?:\/\/[^\s"'`\\\][{}]+$/;
+
+// IPv4 ranges that are not public, as [base address, prefix length]
+const RESERVED_V4: [string, number][] = [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.0.0.0", 24],
+  ["192.0.2.0", 24],
+  ["192.168.0.0", 16],
+  ["198.18.0.0", 15],
+  ["198.51.100.0", 24],
+  ["203.0.113.0", 24],
+  ["224.0.0.0", 3], // multicast and reserved, through 255.255.255.255
+];
+
+const toInt = (ip: string) =>
+  ip.split(".").reduce((n, octet) => n * 256 + Number(octet), 0);
+const inRange = (ip: string, [base, bits]: [string, number]) =>
+  Math.floor(toInt(ip) / 2 ** (32 - bits)) ===
+  Math.floor(toInt(base) / 2 ** (32 - bits));
+
+// names that resolve to this machine, the LAN, or a cloud metadata service
+const PRIVATE_NAME = /(^|\.)(localhost|local|internal|home\.arpa)$/;
+
+/** Whether a URL may be fetched or opened for the user. Names are checked as
+ *  written, not resolved, so a public name that points at a private address
+ *  (127.0.0.1.nip.io, DNS rebinding) still passes, and the browser follows
+ *  redirects before the landed URL is checked. Relay-side curl runs without
+ *  -L, so its redirects are not followed. */
+export function isSafeFetchUrl(u: string): boolean {
+  if (!SAFE_URL.test(u)) return false;
+  let host: string;
+  try {
+    host = new URL(u).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (host.endsWith(".")) host = host.slice(0, -1);
+  // the URL parser has already turned 127.1, 0x7f.0.0.1 and 2130706433
+  // into dotted decimal
+  if (isIP(host) === 4) return !RESERVED_V4.some((r) => inRange(host, r));
+  return host.includes(".") && !PRIVATE_NAME.test(host);
+}

package/src/index.ts

@@ -14,6 +14,7 @@ import { RebindRemote, ServerError } from "@rebind.gg/client-ts";
 import { z } from "zod";
 import pkg from "../package.json";
 import { mapToImage } from "./coords.ts";
+import { isSafeFetchUrl } from "./fetch-guard.ts";
 import { renderScreenshot } from "./image.ts";
 import { normalizeCombo } from "./keys.ts";
 import { llmStep, type Msg } from "./llm.ts";
@@ -114,40 +115,11 @@ const MEDITATE_TOTAL_CHARS = 600_000;
 const MEDITATE_DL_MAX_BYTES = 26_214_400; // 25 MiB
 const MEDITATE_DL_TIMEOUT_S = 45;
 
-/** URLs the model may visit/download: plain http(s), no quotes/brackets that
- *  could escape the shell or Lua long-bracket quoting they are spliced into. */
-const SAFE_URL = /^https?:\/\/[^\s"'`\\\][]+$/;
-
 /** Front app is a browser we can drive (Safari included — it fails later at the
  *  javascript: step, but it is still a browser, not a terminal we'd type into). */
 const BROWSER_RE =
   /chrome|chromium|brave|firefox|edge|opera|vivaldi|arc|safari/i;
 
-/** SSRF guard: block loopback, RFC1918, link-local (incl. cloud metadata), and
- *  *.local before a model-chosen URL reaches the real browser or relay curl.
- *  Hostname-based — does not defeat DNS rebinding, but stops the direct hits. */
-function isSafeFetchUrl(u: string): boolean {
-  if (!SAFE_URL.test(u)) return false;
-  let host: string;
-  try {
-    host = new URL(u).hostname.toLowerCase();
-  } catch {
-    return false;
-  }
-  if (host === "localhost" || host === "0.0.0.0" || host.endsWith(".local"))
-    return false;
-  if (
-    /^(127\.|10\.|192\.168\.|169\.254\.|::1$|\[?::1\]?$|fe80:|fc|fd)/i.test(
-      host,
-    )
-  )
-    return false;
-  const m = /^(\d+)\.(\d+)\./.exec(host);
-  if (m && Number(m[1]) === 172 && Number(m[2]) >= 16 && Number(m[2]) <= 31)
-    return false;
-  return true;
-}
-
 /** per-asset inlined-content budget fed to the model (text/csv sources) */
 const MEDITATE_ASSET_CHARS = 60_000;
 /** a fetched page shorter than this is a JS shell, not content — go to the browser */
@@ -530,6 +502,7 @@ async function main() {
       // an app finishing launch) and the payload would be typed into it instead.
       if (!BROWSER_RE.test(await frontApp())) {
         if (!appName) return null;
+        // App.Activate focuses a running browser only; a closed one stays closed
         await client.luaExec(
           `App.Activate(${JSON.stringify(appName)}) return true`,
         );
@@ -649,15 +622,11 @@ async function main() {
     await sleep(3000);
   };
 
-  // Capture the display under the cursor, render it, and record the image->screen
-  // mapping on the session so a subsequent verifiedClick(mapImagePoint(...)) lands
-  // correctly. Returns the webp bytes as a base64 data URL for vision models.
-  const captureScreen = async (): Promise<{
-    dataUrl: string;
-    width: number;
-    height: number;
-  }> => {
-    const cap = await client.screenCapture({});
+  // Capture a display (default: the one under the cursor), render it, and record
+  // the image->screen mapping on the session so a subsequent
+  // verifiedClick(mapImagePoint(...)) lands correctly.
+  const captureScreen = async (display?: number) => {
+    const cap = await client.screenCapture({ display });
     const shot = await renderScreenshot({
       png: Buffer.from(cap.image, "base64"),
       logicalWidth: cap.display.width,
@@ -675,11 +644,7 @@ async function main() {
       imageWidth: shot.width,
       imageHeight: shot.height,
     };
-    return {
-      dataUrl: `data:image/webp;base64,${shot.data.toString("base64")}`,
-      width: shot.width,
-      height: shot.height,
-    };
+    return { cap, shot };
   };
 
   // Resolve a window (title substring, or the front window when want=""),
@@ -737,24 +702,7 @@ return { ok = true, proc = proc }
       },
     },
     async ({ display }) => {
-      const cap = await client.screenCapture({ display });
-      const shot = await renderScreenshot({
-        png: Buffer.from(cap.image, "base64"),
-        logicalWidth: cap.display.width,
-        logicalHeight: cap.display.height,
-        cursor: {
-          x: cap.cursor.x - cap.display.x,
-          y: cap.cursor.y - cap.display.y,
-        },
-      });
-      session.lastShot = {
-        displayIndex: cap.display.index,
-        originX: cap.display.x,
-        originY: cap.display.y,
-        scale: shot.scale,
-        imageWidth: shot.width,
-        imageHeight: shot.height,
-      };
+      const { cap, shot } = await captureScreen(display);
       const win = await client.systemWindow().catch(() => null);
       const lines = [
         `display ${cap.display.index}: ${cap.display.width}x${cap.display.height} at (${cap.display.x}, ${cap.display.y})${cap.display.primary ? " (primary)" : ""}`,
@@ -1446,7 +1394,8 @@ return { ok = Window.IsActive(h), name = name }
         // Fetch a URL's text relay-side. This is the primary way content is
         // gathered: a GET returns exactly what the server has, where driving the
         // browser to the same URL costs HID, focus, and a fragile extraction.
-        // Same SSRF guard and size/time limits as the download path.
+        // Same SSRF guard and size/time limits as the download path, and no -L:
+        // a redirect target is a host the guard never checked.
         const fetchText = async (
           u: string,
           maxChars: number,
@@ -1454,7 +1403,7 @@ return { ok = Window.IsActive(h), name = name }
           if (!isSafeFetchUrl(u)) return null;
           try {
             const out = await client.luaExec(
-              `local r = System.Exec([[curl -fsSL --proto '=http,https' --max-filesize ${MEDITATE_DL_MAX_BYTES} --max-time ${MEDITATE_DL_TIMEOUT_S} '${u}']], { timeout = ${(MEDITATE_DL_TIMEOUT_S + 10) * 1000} }) return r.stdout`,
+              `local r = System.Exec([[curl -fsS -g --proto '=http,https' --max-filesize ${MEDITATE_DL_MAX_BYTES} --max-time ${MEDITATE_DL_TIMEOUT_S} '${u}']], { timeout = ${(MEDITATE_DL_TIMEOUT_S + 10) * 1000} }) return r.stdout`,
             );
             const s = String(out ?? "");
             return s.trim() ? s.slice(0, maxChars) : null;
@@ -1567,7 +1516,12 @@ return { ok = Window.IsActive(h), name = name }
           if (haveBrowser)
             await client.luaExec(positionLua("", 0, 0, 1200, 900));
           if (isShell) {
-            if (haveBrowser) first = await extractPage(browser, pageUrl);
+            const d = haveBrowser ? await extractPage(browser, pageUrl) : null;
+            if (d && isSafeFetchUrl(d.split("\n")[1] ?? "")) first = d;
+            else if (d)
+              note(
+                "rendered page refused: the browser landed on a host the fetch guard refuses",
+              );
             if (!first) first = raw; // no browser — the shell is all we have
           }
           // PREPEND, never append: the per-page budget keeps only the first
@@ -1649,11 +1603,12 @@ return { ok = Window.IsActive(h), name = name }
                   .replace(/[^\w.-]/g, "_")
                   .slice(0, 80) || "asset";
               const path = `${dlDir}/${assets.length}-${name}`;
-              // isSafeFetchUrl bans quotes/brackets AND private hosts, so this
-              // splice is injection-safe; --proto and no -L block redirect-SSRF,
+              // isSafeFetchUrl bans quotes, brackets and braces and private
+              // hosts, and -g turns curl's URL globbing off, so this splice is
+              // injection-safe; --proto and no -L block redirect-SSRF,
               // --max-filesize/--max-time bound a hostile response.
               const exit = await client.luaExec(
-                `local r = System.Exec([[curl -fsS --proto '=http,https' --max-filesize ${MEDITATE_DL_MAX_BYTES} --max-time ${MEDITATE_DL_TIMEOUT_S} -o '${path}' '${u}']], { timeout = ${(MEDITATE_DL_TIMEOUT_S + 10) * 1000} }) return r.exit`,
+                `local r = System.Exec([[curl -fsS -g --proto '=http,https' --max-filesize ${MEDITATE_DL_MAX_BYTES} --max-time ${MEDITATE_DL_TIMEOUT_S} -o '${path}' '${u}']], { timeout = ${(MEDITATE_DL_TIMEOUT_S + 10) * 1000} }) return r.exit`,
               );
               const ok = Number(exit) === 0;
               // inline text/csv content so the model can READ the source, not
@@ -1729,7 +1684,11 @@ return { ok = Window.IsActive(h), name = name }
           if (haveBrowser) {
             await gotoUrl(pageUrl);
             try {
-              const shot = await captureScreen();
+              const { shot } = await captureScreen();
+              if (!isSafeFetchUrl(await tabUrl(browser || front)))
+                throw new Error(
+                  "the browser landed on a URL the fetch guard refuses",
+                );
               const vstep = await llmStep(
                 [
                   { role: "system", content: MEDITATE_VISION_SYS },
@@ -1737,7 +1696,12 @@ return { ok = Window.IsActive(h), name = name }
                     role: "user",
                     content: [
                       { type: "text", text: "Read this page." },
-                      { type: "image_url", image_url: { url: shot.dataUrl } },
+                      {
+                        type: "image_url",
+                        image_url: {
+                          url: `data:image/webp;base64,${shot.data.toString("base64")}`,
+                        },
+                      },
                     ],
                   },
                 ],
@@ -1756,7 +1720,7 @@ return { ok = Window.IsActive(h), name = name }
               }
             } catch (e) {
               note(
-                `vision pass skipped (model may lack image input): ${e instanceof Error ? e.message : e}`,
+                `vision pass skipped: ${e instanceof Error ? e.message : e}`,
               );
             }
           }

package/src/rebind.d.luau

@@ -190,10 +190,10 @@ export type InputDevice = {
   id: string,
   name: string,
   nickname: string?,
-  kind: "keyboard" | "mouse" | "other",
+  kind: "keyboard" | "mouse" | "gamepad" | "joystick" | "other",
   vid: string,
   pid: string,
-  source: "vm" | "host",
+  source: "vm",
   exact: boolean,
 }
 
@@ -445,9 +445,8 @@ export type RebindInfo = {
   version: string,
   name: string,
   runtime_uuid: string,
-  id: string?,
   instance: string,
-  -- host operating system: "windows" | "macos" | "linux"
+  -- host operating system: "windows" | "macos"
   platform: string,
 }
 
@@ -541,9 +540,153 @@ export type RbPhone = {
   notify: (text: string, title: string?) -> PhoneResult,
 }
 
+-- a colour is "#rrggbb" or "#rrggbbaa"; in widget text it may also be a theme
+-- role: "text", "dim", "faint", "accent", "positive", "warning" or "danger"
+export type OverlaySpan = string | { any }
+
+-- a string (a newline starts a line) or one line of spans
+export type OverlayText = string | { OverlaySpan }
+
+-- one draw operation in a surface, in logical units from its top-left corner
+export type OverlayOp = {
+  kind: "rect" | "text",
+  x: number?,
+  y: number?,
+  -- rect
+  w: number?,
+  h: number?,
+  fill: string?,
+  border: string?,
+  border_width: number?,
+  radius: number?,
+  -- true (50% black), false, or the shadow's opacity from 0 to 1
+  shadow: (boolean | number)?,
+  -- text: one line, as text plus color and bold, or as spans
+  text: string?,
+  spans: { OverlaySpan }?,
+  color: string?,
+  bold: boolean?,
+  size: number?,
+}
+
+-- where a surface goes: x and y in rb.screen coordinates, or an anchor
+-- ("top-left", "top", "top-right", "left", "center", "right", "bottom-left",
+-- "bottom", "bottom-right") on a display ("active": the foreground window's
+-- monitor, "primary", "mouse"), moved offset_x and offset_y inward
+export type OverlayPlacement = {
+  x: number?,
+  y: number?,
+  anchor: string?,
+  display: ("active" | "primary" | "mouse")?,
+  offset_x: number?,
+  offset_y: number?,
+}
+
+export type OverlaySurfaceOptions = OverlayPlacement & {
+  width: number,
+  height: number,
+  opacity: number?,
+  ops: { OverlayOp }?,
+}
+
+export type OverlaySurface = {
+  -- merges fields into the surface; x/y and anchor/display replace each other
+  set: (self: OverlaySurface, fields: { [string]: any }) -> OverlaySurface,
+  draw: (self: OverlaySurface, ops: { OverlayOp }) -> OverlaySurface,
+  remove: (self: OverlaySurface) -> (),
+}
+
+-- shared by the widgets; theme is a name from rb.overlay.themes or a table
+-- of the same roles
+export type OverlayWidgetOptions = OverlayPlacement & {
+  theme: (string | { [string]: any })?,
+  size: number?,
+}
+
+export type OverlayToastOptions = OverlayWidgetOptions & {
+  title: string?,
+  meta: string?,
+  -- ms on screen (default 4000)
+  duration: number?,
+  -- ms to wait for hidden overlays to show before giving up (default 60000)
+  expires: number?,
+  max_width: number?,
+}
+
+export type OverlayToast = {
+  close: () -> (),
+}
+
+export type OverlayMenuItem = string | {
+  label: string,
+  hint: string?,
+  action: ((index: number, item: any) -> ())?,
+}
+
+export type OverlayMenuOptions = OverlayWidgetOptions & {
+  title: string?,
+  subtitle: string?,
+  width: number?,
+  keep_open: boolean?,
+  on_select: ((index: number, item: any) -> ())?,
+  on_close: (() -> ())?,
+}
+
+export type OverlayMenu = {
+  selected: number,
+  select: (index: number) -> (),
+  close: () -> (),
+}
+
+export type OverlayStatus = {
+  set: (text: OverlayText) -> OverlayStatus,
+  remove: () -> (),
+}
+
+export type OverlayProgressOptions = OverlayWidgetOptions & {
+  -- logical units (default 320)
+  width: number?,
+}
+
+export type OverlayProgress = {
+  set: (fraction: number?, label: string?) -> OverlayProgress,
+  remove: () -> (),
+}
+
+export type RbOverlay = {
+  -- a surface you draw yourself; at most 16 per script covering at most
+  -- 2,000,000 square units together, removed when the script stops
+  surface: (options: OverlaySurfaceOptions) -> OverlaySurface,
+  -- width and height of one line of text in the bundled monospace face
+  measure: (text: string, size: number?, bold: boolean?) -> (number, number),
+  -- false only when the OS is known to hide overlays (Windows: an exclusive
+  -- full-screen Direct3D game; macOS: the overlays on screen covered for 2
+  -- seconds, so with none on screen it is true)
+  visible: () -> boolean,
+  -- removes every surface of this script
+  clear: () -> (),
+  -- "rebind", "rebind-light", "catppuccin", "tokyo-night", "contrast"
+  themes: { [string]: { [string]: any } },
+  -- a timed notification; toasts at one anchor stack, and one asked for while
+  -- overlays are hidden waits until they show or it expires. A waiting toast
+  -- that then cannot show is dropped with a warning in the script's log.
+  toast: (text: OverlayText, options: OverlayToastOptions?) -> OverlayToast,
+  -- a keyboard menu: while open it takes Up, Down, Enter, Escape and 1 to 9 and
+  -- swallows them. A pick closes it (unless keep_open), then runs the item's
+  -- action and on_select. Losing focus or the OS hiding overlays also closes
+  -- it; on_close runs for every close except rb.overlay.clear() and stopping.
+  -- nil and a reason when overlays are hidden, the script is unfocused, or a
+  -- menu is already open, in this script or another.
+  menu: (items: { OverlayMenuItem }, options: OverlayMenuOptions?) -> (OverlayMenu?, string?),
+  -- a one-line strip that stays until removed
+  status: (text: OverlayText, options: OverlayWidgetOptions?) -> OverlayStatus,
+  -- a labelled bar, fraction 0 to 1
+  progress: (label: string, fraction: number?, options: OverlayProgressOptions?) -> OverlayProgress,
+}
+
 -- 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.
+-- handler receives. For down, up, scroll and axis, a handler that returns
+-- false swallows the input; for move only with mouse_block=true.
 export type Event =
   | "start" -- ()
   | "stop" -- ()
@@ -557,6 +700,7 @@ export type Event =
   | "move" -- (dx: number, dy: number, device: InputDevice?) hardware mode only
   | "scroll" -- (delta: number, device: InputDevice?)
   | "scroll_h" -- (delta: number)
+  | "axis" -- (axis: string, value: number, device: InputDevice?) hardware mode only
   | "input_down" -- (key: string, device: InputDevice?)
   | "input_up" -- (key: string, duration_ms: number, device: InputDevice?)
   | "input_move" -- (dx: number, dy: number, device: InputDevice?)
@@ -577,9 +721,19 @@ export type Event =
 -- system:      PrintScreen, Pause, Menu
 -- numpad:      Kp0-Kp9, KpPlus, KpMinus, KpMultiply, KpDivide, KpEnter, KpDot
 --
--- HID output only:
+-- delivered as input only in hardware mode:
 -- function:    F13-F24
--- media:       MediaNext, MediaPrev, MediaStop, MediaPlay, VolumeUp, VolumeDown, Mute
+-- media:       MediaNext, MediaPrev, MediaStop, MediaPlay, VolumeUp, VolumeDown, VolumeMute
+--
+-- game controllers, hardware mode only (named by position, Xbox letters):
+-- buttons:     PadA (bottom), PadB (right), PadX (left), PadY (top), PadLB,
+--              PadRB, PadLT, PadRT, PadView, PadMenu, PadHome, PadLS, PadRS,
+--              PadUp, PadDown, PadLeft, PadRight, PadP1-PadP4 (paddles)
+-- other pads:  Joy1-Joy32, in the order the controller reports them
+-- axes:        LeftX, LeftY, RightX, RightY (-1..1, up and left negative),
+--              LT, RT (0..1); the "axis" event and input.axis use these
+--
+-- HID output and bind chord modifiers only:
 -- aliases:     Numpad0-9, NP0-9, NPAdd, NPSubtract, NPMultiply, NPDivide, NPEnter,
 --              NPDecimal, Ctrl, Shift, Alt, Win, Meta, Del, PgUp, PgDn, etc.
 
@@ -647,21 +801,36 @@ declare rb: {
     type: (text: string) -> (),
     typewriter: (text: string, delay_ms: number?) -> (),
     move: (dx: number, dy: number) -> (),
-    move_to: (x: number, y: number) -> (),
+    -- exact in Windows and macOS software mode; on a Rebind Link it moves,
+    -- rereads the cursor and corrects until within 2 px (about 150 ms at
+    -- most), waiting with sleep in rb.run and blocking elsewhere. With ms
+    -- it glides there over ms on an eased path; a duration needs rb.run or
+    -- rb.async.
+    move_to: (x: number, y: number, ms: number?) -> (),
     scroll: (amount: number) -> (),
+    -- deprecated: the mode is stored but no longer changes move_to
     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.
+    -- Rebind Link whose USB profile has a joypad; raises otherwise. down, up,
+    -- press and combo also press controller buttons ("PadA").
     joypad: (state: JoypadState?) -> (),
-    -- back to neutral; the relay also does this when a script stops or errors
+    -- holds one controller axis (LeftX..RightY -1..1, LT/RT 0..1) until set
+    -- again or reset; it wins over a captured controller's value
+    axis: (name: string, value: number) -> (),
+    -- drops what scripts set, keeping what a captured controller holds; the
+    -- relay also does this when a script stops or errors
     joypad_reset: () -> (),
   },
   input: {
     is_down: (code: string) -> boolean,
+    -- a controller axis by name, 0 at rest
+    axis: (name: string) -> number,
+    -- the devices Rebind has identified (3.12.0); empty in software mode
+    devices: () -> { InputDevice },
     duration: (code: string) -> number,
     keys: () -> { string },
     mouse_pos: () -> MousePos,
@@ -763,8 +932,9 @@ declare rb: {
     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.
+  -- Windows matches executable names (".exe" optional) and cannot hide.
+  -- activate focuses a running app only (it needs Accessibility on macOS);
+  -- start one with rb.system.exec_detached (permission: exec).
   app: {
     front: () -> AppInfo?,
     is_front: (name: string) -> boolean,
@@ -784,13 +954,15 @@ declare rb: {
     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,
+    -- options.host binds one IP ("127.0.0.1" keeps it on this computer); default all interfaces
+    ws_listen: (port: number, handlers: WsListenHandlers, options: { host: string? }?) -> 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?,
   },
+  -- permission: exec
   pipe: {
     open: (name: string, options: { size: number? }?) -> PipeHandle,
   },
@@ -805,7 +977,7 @@ declare rb: {
     -- 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.
+    -- recursive; raises when the directory does not exist or cannot be removed.
     rmdir: (path: string) -> boolean,
     copy: (src: string, dst: string) -> (),
     move: (src: string, dst: string) -> (),
@@ -872,6 +1044,7 @@ declare rb: {
   },
   env: {
     get: (name: string) -> string?,
+    -- Requires the 'exec' permission.
     set: (name: string, value: string) -> (),
     home: () -> string?,
     config: () -> string?,
@@ -893,6 +1066,8 @@ declare rb: {
   -- Rebind Pro; require("@rebind/pro") returns rb
   ai: RbAi,
   phone: RbPhone,
+  -- drawing on screen over every app, games included (Windows and macOS)
+  overlay: RbOverlay,
 }
 
 -- v1 names
@@ -954,8 +1129,13 @@ declare HID: {
   Type: (text: string) -> (),
   Typewriter: (text: string, delayMs: number?) -> (),
   Move: (dx: number, dy: number) -> (),
-  MoveTo: (x: number, y: number) -> (),
+  -- exact in Windows and macOS software mode; on a Rebind Link it moves,
+  -- rereads the cursor and corrects until within 2 px (about 150 ms at
+  -- most), waiting with Sleep in Run and blocking elsewhere. With ms it
+  -- glides there over ms on an eased path; a duration needs Run or Async.
+  MoveTo: (x: number, y: number, ms: number?) -> (),
   Scroll: (amount: number) -> (),
+  -- deprecated: the mode is stored but no longer changes MoveTo
   SetMouseMode: (mode: string) -> (),
   GetMouseMode: () -> string,
   -- keyboard HID usage for a key name, or nil (media keys return nil). Down,
@@ -964,8 +1144,13 @@ declare HID: {
   -- set the whole joypad state (last write wins across scripts). Needs a
   -- Rebind Link whose USB profile has a joypad; raises otherwise. Keyboard
   -- and mouse calls raise the same way when the profile leaves them out.
+  -- Down, Up, Press and Combo also press controller buttons ("PadA").
   Joypad: (state: JoypadState?) -> (),
-  -- back to neutral; the relay also does this when a script stops or errors
+  -- hold one controller axis (LeftX..RightY -1..1, LT/RT 0..1) until set
+  -- again or reset; it wins over a captured controller's value
+  Axis: (name: string, value: number) -> (),
+  -- drop what scripts set, keeping what a captured controller holds; the
+  -- relay also does this when a script stops or errors
   JoypadReset: () -> (),
 }
 
@@ -973,6 +1158,10 @@ declare HID: {
 
 declare Input: {
   IsDown: (code: string) -> boolean,
+  -- a controller axis by name, 0 at rest
+  GetAxis: (name: string) -> number,
+  -- the devices Rebind has identified (3.12.0); empty in software mode
+  Devices: () -> { InputDevice },
   GetDuration: (code: string) -> number,
   GetActiveKeys: () -> { string },
   GetMousePos: () -> MousePos,
@@ -1118,12 +1307,13 @@ declare Window: {
 }
 
 -- app namespace: application-level control (Keyboard Maestro's Application
--- Control). macOS: 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.
+-- Control). Activate focuses a running app and never launches one; start an
+-- app with System.ExecDetached (permission: exec). macOS: names match
+-- case-insensitively by app display name; Activate needs Accessibility;
+-- Quit/IsHidden drive an AppleEvent and prompt for macOS Automation
+-- permission on first use; Quit leaves an app that is not running alone.
 -- Windows: names are executable names (case-insensitive, ".exe" optional);
--- Activate focuses a running app and does not launch one; Quit closes its
--- windows; Hide/IsHidden raise. Linux: every call raises.
+-- Quit closes its windows; Hide/IsHidden raise.
 
 declare App: {
   Front: () -> AppInfo?,
@@ -1146,7 +1336,7 @@ declare Net: {
   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,
+  WSListen: (port: number, handlers: WsListenHandlers, options: { host: string? }?) -> WsServerHandle,
   WSConnect: (url: string, handlers: WsConnectHandlers) -> WsConnectHandle,
   -- bind a UDP socket; handler receives each datagram's raw bytes and sender.
   UDPListen: (bindIp: string, port: number, handler: (data: string, ip: string, port: number) -> ()) -> UdpHandle,
@@ -1154,7 +1344,7 @@ declare Net: {
   LocalIP: () -> string?,
 }
 
--- pipe namespace
+-- pipe namespace (permission: exec)
 
 declare Pipe: {
   Open: (name: string, options: { size: number? }?) -> PipeHandle,
@@ -1173,7 +1363,7 @@ declare File: {
   -- script dir (the File.* jail); absolute paths are rejected.
   List: (path: string?) -> { string },
   MkDir: (path: string) -> boolean,
-  -- recursive; returns true even when the directory did not exist.
+  -- recursive; raises when the directory does not exist or cannot be removed.
   RmDir: (path: string) -> boolean,
   Copy: (src: string, dst: string) -> (),
   Move: (src: string, dst: string) -> (),
@@ -1266,6 +1456,7 @@ declare Codec: {
 
 declare Env: {
   Get: (name: string) -> string?,
+  -- Requires the 'exec' permission.
   Set: (name: string, value: string) -> (),
   Home: () -> string?,
   Config: () -> string?,
@@ -1300,6 +1491,7 @@ declare Registry: {
 -- declare function OnMove(dx: number, dy: number, device: InputDevice?): boolean?  -- return value only used with mouse_block=true (hardware mode only)
 -- declare function OnScroll(delta: number, device: InputDevice?): boolean?
 -- declare function OnScrollH(delta: number): boolean?
+-- declare function OnAxis(axis: string, value: number, device: InputDevice?): boolean?  -- hardware mode only
 -- declare function OnInputDown(key: string, device: InputDevice?): ()
 -- declare function OnInputUp(key: string, durationMs: number, device: InputDevice?): ()
 -- declare function OnInputMove(dx: number, dy: number, device: InputDevice?): ()

package/src/session.ts

@@ -87,12 +87,12 @@ export class Session {
   /**
    * Move the OS cursor to absolute screen (x, y).
    *
-   * The relay's hid.move_smooth / hid.move_to derive their delta from a cached
-   * cursor position that goes stale and flings the pointer to a screen edge
-   * (observed: target (800,500) landing at (0,0)). Relative counts map 1:1 to
-   * pixels, so we read the REAL cursor, glide the residual in small relative
-   * steps (human-like, not an instant jump), then read back and correct against
-   * the true cursor. Converges to the exact pixel, usually in a single pass.
+   * Relays before 3.10.1 derived hid.move_to's move from a stale
+   * cached cursor and could fling the pointer to a screen edge (observed:
+   * target (800,500) landing at (0,0)), so this reads the REAL cursor, glides
+   * the residual in small relative steps (human-like, not an instant jump),
+   * then reads back and corrects against the true cursor. Converges to the
+   * exact pixel, usually in a single pass.
    */
   async moveTo(x: number, y: number): Promise<Point & { passes: number }> {
     await this.ensureCalibrated();