@rebind.gg/mcp-server 0.3.1 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@ Stdio MCP server that turns [Rebind](https://rebind.gg) into a computer-use tool
 - [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 --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.
+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. The `observe_*` tools need **Allow observation** turned on there, Remote Control 0.5.0 and Rebind 3.15.0.
 
 ## Install
 
@@ -61,6 +61,11 @@ Connects, waits up to a minute for the approval prompt on a first run, takes a c
 | `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`. |
+| `observe_start` / `observe_stop` | Start and stop a recording of the user: every key and button they press (passwords included), mouse movement, the active window, and screenshots, saved in Rebind's observations folder. The server's instructions tell the agent to ask before starting one. It also stops when the server disconnects. |
+| `observe_mark` | Add a note (`mark`, `success`, `failure`, `ai` or `own`, with a label and JSON data) to the recording the server started. |
+| `observe_list` | Every recording in the observations folder, newest first, including ones made in the app or with `rebind observe`. |
+| `observe_events` | A recording's log lines from `from_seq`, 64 KB at a time unless `max_bytes` says otherwise, and `next`, the seq to read on from. |
+| `observe_frame` | One screenshot from a recording, as a `frame` or `crop` line names it, returned as an image. |
 | `list_displays` / `list_windows` / `focus_window` / `position_window` / `active_window` | Display and window enumeration, focus, and placement. |
 | `get_cursor` / `wait` / `calibrate` | Cursor readback, pauses, and the mouse scale probe. |
 | `delegate_task` / `rebind_versus` | Server-side reasoning helpers with no desktop access: one bounded text task, or parallel critics that attack a plan. Registered only with `REBIND_ALLOW_DELEGATION=1` (spends OpenRouter credits). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebind.gg/mcp-server",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "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": {
@@ -41,7 +41,7 @@
   "scripts": {
     "start": "bun run src/index.ts",
     "selftest": "bun run src/index.ts --selftest",
-    "test": "bun test src/ tests/",
+    "test": "bun test tests/",
     "typecheck": "tsc --noEmit",
     "bench": "bun run bench/runner.ts",
     "bench:selftest": "bun run bench/runner.ts --selftest",
@@ -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,9 +14,11 @@ 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";
+import { observeRefusal } from "./observe.ts";
 import {
   BATCHING_DOCTRINE,
   DETERMINISTIC_WORK_DOCTRINE,
@@ -24,6 +26,7 @@ import {
   KEY_DESC,
   LUA_DOCS_DESC,
   modifierNote,
+  OBSERVE_DOCTRINE,
   type OS,
   openAppHow,
   PROBE_CLIS_CMD,
@@ -114,40 +117,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 */
@@ -338,6 +312,7 @@ async function buildInstructions(
     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),
+    OBSERVE_DOCTRINE,
     "run_lua chunks execute once and must end with `return <value>`. File.* paths are relative to the script dir (absolute rejected); System.Exec takes real absolute paths.",
     `Full run_lua Luau SDK — every namespace and signature (do not guess APIs):\n${sdk}`,
   ]
@@ -530,6 +505,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 +625,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 +647,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 +705,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)" : ""}`,
@@ -1220,6 +1171,191 @@ return { ok = Window.IsActive(h), name = name }
     async () => text(await v1Sdk()),
   );
 
+  // --- observation: rb.observe in Remote Control (observe.* commands) ---
+  // A refusal the user fixes (Allow observation off, an older Remote Control
+  // or Rebind) comes back as a plain error result; anything else throws.
+  const observe = async (
+    command: string,
+    args: Record<string, unknown>,
+    answer: (r: any) => any,
+  ) => {
+    try {
+      return await answer(await client.call(`observe.${command}`, args));
+    } catch (e) {
+      const refusal = observeRefusal(e);
+      if (refusal === null) throw e;
+      return { ...text(refusal), isError: true };
+    }
+  };
+  const json = (v: unknown) => text(JSON.stringify(v, null, 2));
+
+  register(
+    "observe_start",
+    {
+      description:
+        "Start recording the USER: every key and button they press, mouse movement, the active window, and screenshots, saved in Rebind's observations folder. " +
+        "Ask the user first and start only after they agree. One recording runs at a time. It ends after `seconds`, at `stop_key`, on observe_stop, or when this server disconnects. " +
+        "Needs Allow observation on in Remote Control's Options. Returns the recording's status, including its id.",
+      inputSchema: {
+        seconds: z
+          .number()
+          .int()
+          .min(1)
+          .max(14400)
+          .optional()
+          .describe("how long to record (default 120)"),
+        stop_key: z
+          .string()
+          .optional()
+          .describe(
+            'a keyboard key that ends the recording early, such as "F8"',
+          ),
+        goal: z
+          .string()
+          .max(500)
+          .optional()
+          .describe("what the recording is for, saved with it"),
+        frame_ms: z
+          .number()
+          .int()
+          .min(0)
+          .max(30000)
+          .optional()
+          .describe(
+            "ms between screenshots while nothing happens (default 1000; 0 turns them off)",
+          ),
+        frame_edge: z
+          .number()
+          .int()
+          .min(256)
+          .max(2048)
+          .optional()
+          .describe("long edge of the screenshots in pixels (default 1024)"),
+      },
+    },
+    async (args) => observe("start", args, (r) => json(r.session)),
+  );
+
+  register(
+    "observe_mark",
+    {
+      description:
+        "Add a note to the recording this server started, among the inputs around it: a moment worth finding later, a success, or a failure. Returns whether it was queued (false when no recording of this server's is running).",
+      inputSchema: {
+        kind: z
+          .enum(["mark", "success", "failure", "ai", "own"])
+          .default("mark"),
+        label: z.string().max(200).optional(),
+        data: z.unknown().optional().describe("any JSON value, up to 8 KB"),
+      },
+    },
+    async (args) =>
+      observe("mark", args, (r) =>
+        text(
+          r.queued
+            ? "marked"
+            : "not marked: no recording of this server's is running",
+        ),
+      ),
+  );
+
+  register(
+    "observe_stop",
+    {
+      description:
+        "Stop the recording this server started. Returns its final counts and the reason it ended.",
+    },
+    async () => observe("stop", {}, (r) => json(r.session)),
+  );
+
+  register(
+    "observe_list",
+    {
+      description:
+        "List every recording in Rebind's observations folder, newest first, including ones the user made in the app or with `rebind observe`: id, name, goal, owner, times, and counts.",
+    },
+    async () => observe("list", {}, (r) => json(r.recordings)),
+  );
+
+  register(
+    "observe_events",
+    {
+      description:
+        "Read a recording's log lines (events.jsonl) in seq order: key and button presses with hold times, mouse movement, scrolls, window changes, frame and crop lines naming screenshots, and marks. " +
+        "Returns `lines` and `next`, the seq to pass as from_seq to read on.",
+      inputSchema: {
+        id: z
+          .string()
+          .describe("the recording id, from observe_list or observe_start"),
+        from_seq: z
+          .number()
+          .int()
+          .min(0)
+          .optional()
+          .describe("first seq (default 0)"),
+        to_seq: z.number().int().min(0).optional().describe("last seq"),
+        max_bytes: z
+          .number()
+          .int()
+          .min(1)
+          .max(4194304)
+          .default(65536)
+          .describe(
+            "stop before this many bytes of lines; at least one line is returned",
+          ),
+      },
+    },
+    async ({ id, ...rest }) =>
+      observe("events", { session: id, ...rest }, (r) =>
+        json({ lines: r.lines, next: r.next }),
+      ),
+  );
+
+  register(
+    "observe_frame",
+    {
+      description:
+        "Show one screenshot from a recording, as a frame or crop line names it (frames/NNNNNN.png, frames/NNNNNN.win.png or crops/NNNNNN.png). " +
+        "It shows the screen as it was then: do not click by its coordinates.",
+      inputSchema: {
+        id: z.string().describe("the recording id"),
+        file: z.string().describe("the `file` of a frame or crop line"),
+        max_edge: z
+          .number()
+          .int()
+          .min(1)
+          .default(1280)
+          .describe("scale the image down so its long edge fits"),
+      },
+    },
+    async ({ id, file, max_edge }) =>
+      observe(
+        "frame",
+        { session: id, file, max_edge },
+        async (r: { data: string; width: number; height: number }) => {
+          const shot = await renderScreenshot({
+            png: Buffer.from(r.data, "base64"),
+            logicalWidth: r.width,
+            logicalHeight: r.height,
+            maxEdge: max_edge,
+          });
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `${file} of recording ${id}: ${shot.width}x${shot.height}`,
+              },
+              {
+                type: "image" as const,
+                data: shot.data.toString("base64"),
+                mimeType: "image/webp",
+              },
+            ],
+          };
+        },
+      ),
+  );
+
   // Server-side subagents. Gated: a stock install ships without them. They make
   // OpenRouter calls (money) and touch no HID, so they register DIRECTLY on the
   // server — NOT through `register()`, whose serial `chain` would let one
@@ -1446,7 +1582,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 +1591,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 +1704,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 +1791,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 +1872,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 +1884,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 +1908,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/observe.ts

@@ -0,0 +1,19 @@
+// the observe_* tools' plain answers when Remote Control refuses an observe.*
+// command for a reason the user fixes, not the agent.
+
+import { ServerError } from "@rebind.gg/client-ts";
+
+/** the text to show for a refusal the user must fix, or null for any other error */
+export function observeRefusal(e: unknown): string | null {
+  if (!(e instanceof ServerError)) return null;
+  switch (e.code) {
+    case "disabled":
+      return "Allow observation is off in Remote Control's Options on the computer running Rebind. Ask the user to turn it on if they want to be recorded; while it is on, a connected program can record every key they press and their screen.";
+    case "unknown_command":
+      return "This Remote Control has no observe commands: it is older than 0.5.0. Ask the user to update the Remote Control package.";
+    case "unavailable":
+      return "This Rebind cannot record observations: it is older than 3.15.0. Ask the user to update Rebind.";
+    default:
+      return null;
+  }
+}

package/src/prompts.ts

@@ -73,6 +73,10 @@ export const DETERMINISTIC_WORK_DOCTRINE =
 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.";
 
+/** MCP server only: the observe_* tools record the user, so they ask first. */
+export const OBSERVE_DOCTRINE =
+  "observe_start records the user, not you: every key and button they press and release (passwords included, by name), mouse movement, the active window, and screenshots of their screen, saved in Rebind's observations folder until they delete it. Use it to watch the user do a task before you script it. Never start one on your own: ask first, saying what it records, for how long, and the stop key if you set one, and start only after the user agrees. Tell them when recording has started and not to type secrets. When they say they are done, call observe_stop, then read the recording with observe_events (log lines in seq order) and observe_frame (the screenshots its frame and crop lines name). observe_list shows every recording, including ones the user made in the app.";
+
 // --- tool descriptions (shared only where the underlying behavior is identical
 // across both surfaces: run_lua, lua_docs, and key all hit the same relay) ---
 
@@ -90,7 +94,7 @@ export const RUN_LUA_DESC =
   '(Sleep, HID.Press, Dialog file pickers, Screen.Capture, Screen.FindImage, Screen.SearchForColor over 200k pixels) error — wait with System.Exec("sleep 0.5") instead, and take screenshots with the screenshot tool, not from a chunk. There is no Lua stdlib `io`/`os`/`require`. ' +
   "Use it to launch apps (System.ExecDetached), place windows (Window.Wait / Window.Move — on macOS the window handle is advisory and Move targets the FRONTMOST window, so bring the app forward first), run shell commands " +
   '(System.Exec(cmd) -> {exit,stdout,stderr}, absolute paths fine; inside a chunk it runs asynchronously on a background thread and does not block, so a slow command is safe), find UI by color in a small region (Screen.SearchForColor({x1,y1,x2,y2}, "rrggbb", tolerance), region under 200k pixels), type, click, read pixels (Screen.GetPixelColor), manage processes. ' +
-  "File.* (Read/Write/Append/ReadJSON/WriteJSON/Exists/Delete/List/MkDir/RmDir/Copy/Move/GetSize/GetTime/GetScriptDir) is jailed to the script dir: paths RELATIVE, absolute rejected. " +
+  "File.* (Read/Write/Append/ReadJSON/WriteJSON/Exists/Delete/List/MkDir/RmDir/Copy/Move/GetSize/GetTime/GetScriptDir/GetDataDir) is jailed to the script dir: paths RELATIVE, absolute rejected. Paths starting \"@data/\" reach the script's data folder (3.13.0), which a chunk does not have. " +
   'A folder described as on the Desktop or in home is reachable at its BARE name from the jail root (e.g. File.List("myfolder")) — never prefix "Desktop/" or "~". ' +
   "JSON is JSON.Parse(s) and JSON.Stringify(v) — there is no JSON.Decode/Encode; for JSON files File.ReadJSON/File.WriteJSON is one call. " +
   "System.Exec commands run in an UNRELATED working directory — a relative shell path does NOT land in the File jail, so do file work with File.* (File.Write always works in the jail), and use absolute paths inside shell commands. " +

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,
 }
 
@@ -407,6 +407,9 @@ export type SliderOpts = WidgetOpts & {
   suffix: string?,
 }
 
+-- a keybind setting holds a key name, or "<key>@<device id>" once the user
+-- restricts it to the device that pressed it; Bind, Bind.Toggle, Bind.Remap
+-- and rb.bind read the suffix as their device filter. A default is a plain key.
 export type KeybindOpts = WidgetOpts
 
 export type SelectOpts = WidgetOpts
@@ -419,6 +422,12 @@ export type TextOpts = WidgetOpts & {
 
 export type ColorOpts = WidgetOpts
 
+export type ListOpts = WidgetOpts & {
+  placeholder: string?,
+  maxLength: number?,
+  max_length: number?,
+}
+
 export type RecordOpts = {
   ignore_mouse: boolean?,
   ignore_keyboard: boolean?,
@@ -432,7 +441,7 @@ export type UiProxy = { [string]: any }
 
 -- bind config for table-style binding
 export type BindConfig = {
-  device: string?, -- nickname or id: the bind answers only to that device
+  device: string?, -- nickname or id: the bind answers only to that device; replaces a pin in the key
   when: ((device: InputDevice?) -> boolean)?,
   action: ((device: InputDevice?) -> boolean?)?,
   release: ((device: InputDevice?) -> ())?,
@@ -445,9 +454,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,
 }
 
@@ -486,7 +494,8 @@ export type RbBindOptions = {
   when: ((device: InputDevice?) -> boolean)?,
   -- runs when the key is released
   release: ((device: InputDevice?) -> ())?,
-  -- nickname or id: the bind answers only to that device
+  -- nickname or id: the bind answers only to that device; replaces a pin in
+  -- the key ("<key>@<device id>", saved by a keybind setting)
   device: string?,
 }
 
@@ -541,9 +550,298 @@ 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" | "image",
+  x: number?,
+  y: number?,
+  -- rect and image; an image defaults to its size in pixels
+  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?,
+  -- image (3.14.0): the bytes of a PNG file, such as
+  -- rb.file.read_bytes("icon.png")
+  png: string?,
+}
+
+-- 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?,
+  -- true shows the surface in screenshots and recordings (3.14.0)
+  capturable: boolean?,
+  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?,
+  -- true shows the widget in screenshots and recordings (3.14.0)
+  capturable: boolean?,
+}
+
+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 OverlayPromptOptions = OverlayWidgetOptions & {
+  title: string?,
+  -- the text to start with
+  value: string?,
+  -- shown faint while the field is empty
+  placeholder: string?,
+  -- characters, 1 to 256 (default 128)
+  max_length: number?,
+  width: number?,
+  on_submit: ((text: string) -> ())?,
+  on_cancel: (() -> ())?,
+  on_close: (() -> ())?,
+}
+
+export type OverlayPrompt = {
+  text: string,
+  set: (text: string) -> (),
+  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 or prompt is already open, in this script or another.
+  menu: (items: { OverlayMenuItem }, options: OverlayMenuOptions?) -> (OverlayMenu?, string?),
+  -- (3.15.0) a one-line text field typed through swallowing binds, so it needs no focus.
+  -- Enter closes it and runs on_submit(text); Escape, close(), losing focus or
+  -- the OS hiding overlays close it and run on_cancel; on_close then runs for
+  -- either. Each key types its US-layout character, Shift picks the shifted
+  -- one, Backspace deletes, Ctrl+V (Cmd+V on macOS) pastes. Ctrl, Alt and Win
+  -- chords reach the app. Holding a key acts once. It holds the same keyboard
+  -- as menu, so it returns the same reasons as menu.
+  prompt: (label: string, options: OverlayPromptOptions?) -> (OverlayPrompt?, 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,
+}
+
+-- rb.observe (3.15.0) records what the user does, as `rebind observe` does:
+-- every key and button with its hold time, mouse movement, the active window
+-- and screenshots, in a session folder the script reads back. It needs the
+-- observe permission, which a script holds only when it declares it, with
+-- min_sdk=3.15.0 or later. A script marks and stops only the session it
+-- started, and renames or deletes only recordings a script made under its
+-- name (owner_kind "script"); it reads every recording.
+-- start, stop, list, events, frame, rename and delete wait for an answer, so
+-- call them inside rb.run; mark and status answer at once.
+
+export type ObserveStartOptions = {
+  -- 1 to 14400 (default 120)
+  seconds: number?,
+  -- a keyboard key that ends the session early, such as "F8"
+  stop_key: string?,
+  -- what the recording is for, up to 500 characters
+  goal: string?,
+  -- ms between idle screenshots, 0 to 30000; 0 turns them off (default 1000)
+  frame_ms: number?,
+  -- the long edge of screenshots, 256 to 2048 pixels (default 1024)
+  frame_edge: number?,
+}
+
+export type ObserveStatus = {
+  id: string,
+  -- the session folder, holding events.jsonl, frames/ and crops/
+  dir: string,
+  elapsed_ms: number,
+  seconds: number,
+  events: number,
+  frames: number,
+  crops: number,
+  marks: number,
+  drops: number,
+  bytes: number,
+  -- the script's name, or the app or CLI that started it
+  owner: string,
+  -- "script" for a session rb.observe started, "client" for the app or CLI
+  owner_kind: string,
+  goal: string?,
+  -- why no screenshots are taken, when they are not
+  frames_off: string?,
+  -- why it ended, once it has
+  reason: string?,
+}
+
+export type ObserveSummary = {
+  id: string,
+  name: string?,
+  goal: string?,
+  owner: string,
+  -- "script" or "client", as on ObserveStatus
+  owner_kind: string,
+  -- epoch ms
+  started_at: number,
+  ended_at: number?,
+  seconds: number,
+  events: number,
+  frames: number,
+  crops: number,
+  marks: number,
+  drops: number,
+  dropped_marks: number,
+  bytes: number,
+  frames_off: string?,
+  reason: string?,
+  -- true while it records
+  running: boolean?,
+}
+
+export type ObserveEvents = {
+  -- events.jsonl lines, each a table with seq, t and kind
+  lines: { { [string]: any } },
+  -- the seq to ask for next
+  next: number,
+}
+
+export type ObserveImage = {
+  mime: string,
+  width: number,
+  height: number,
+  -- the PNG, base64
+  data: string,
+}
+
+export type RbObserve = {
+  -- starts a session this script owns; one session runs at a time
+  start: (options: ObserveStartOptions?) -> ObserveStatus,
+  -- ends the session this script started; its final counts and reason
+  stop: () -> ObserveStatus,
+  -- a note in this script's running session: label up to 200 characters,
+  -- data up to 8 KB as JSON and 32 tables deep. false when this script has
+  -- no session running or the note could not be queued
+  mark: (kind: "mark" | "success" | "failure" | "ai" | "own", label: string?, data: any?) -> boolean,
+  -- the running session, whoever started it, or nil
+  status: () -> ObserveStatus?,
+  -- every recording, newest first
+  list: () -> { ObserveSummary },
+  -- lines from from_seq through to_seq, stopping before max_bytes of them
+  -- (default 262144, at most 4194304) but returning at least one
+  events: (id: string, from_seq: number?, to_seq: number?, max_bytes: number?) -> ObserveEvents,
+  -- "frames/NNNNNN.png", "frames/NNNNNN.win.png" or "crops/NNNNNN.png",
+  -- scaled down to max_edge
+  frame: (id: string, file: string, max_edge: number?) -> ObserveImage,
+  -- names a finished recording; "" clears the name
+  rename: (id: string, name: string) -> ObserveSummary,
+  -- removes a finished recording's folder; returns its id
+  delete: (id: string) -> 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.
+-- 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 +855,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 +876,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.
 
@@ -652,7 +961,6 @@ declare rb: {
     -- 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.
-    -- Not supported on Linux (no cursor source).
     move_to: (x: number, y: number, ms: number?) -> (),
     scroll: (amount: number) -> (),
     -- deprecated: the mode is stored but no longer changes move_to
@@ -662,13 +970,22 @@ declare rb: {
     -- 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,
@@ -682,6 +999,7 @@ declare rb: {
     select: (default: string, choices: { string }, opts: SelectOpts?) -> any,
     text: (default: string, opts: TextOpts?) -> any,
     color: (default: string, opts: ColorOpts?) -> any,
+    list: (default: { string }, opts: ListOpts?) -> any,
     get: (id: string) -> any,
     set: (id: string, value: any) -> (),
     get_all: () -> { [string]: any },
@@ -770,8 +1088,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,
@@ -791,17 +1110,21 @@ 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,
   },
-  -- paths are relative to the script directory; absolute paths are rejected
+  -- paths are relative to the script directory; absolute paths are rejected.
+  -- "@data/..." paths (3.13.0) reach the script's data folder instead, kept
+  -- outside the scripts tree across updates and deleted with the script.
   file: {
     read: (path: string) -> string,
     read_bytes: (path: string) -> string,
@@ -812,13 +1135,16 @@ 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) -> (),
     read_json: (path: string) -> any,
     write_json: (path: string, value: any) -> (),
     script_dir: () -> string,
+    -- absolute path of the script's data folder (3.13.0); raises for a
+    -- script with no file
+    data_dir: () -> string,
     size: (path: string) -> number,
     time: (path: string) -> number,
     is_dir: (path: string) -> boolean,
@@ -879,6 +1205,7 @@ declare rb: {
   },
   env: {
     get: (name: string) -> string?,
+    -- Requires the 'exec' permission.
     set: (name: string, value: string) -> (),
     home: () -> string?,
     config: () -> string?,
@@ -900,6 +1227,10 @@ 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,
+  -- recording input, windows and screenshots (3.15.0); permission: observe
+  observe: RbObserve,
 }
 
 -- v1 names
@@ -965,7 +1296,6 @@ declare HID: {
   -- 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.
-  -- Not supported on Linux (no cursor source).
   MoveTo: (x: number, y: number, ms: number?) -> (),
   Scroll: (amount: number) -> (),
   -- deprecated: the mode is stored but no longer changes MoveTo
@@ -977,8 +1307,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: () -> (),
 }
 
@@ -986,6 +1321,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,
@@ -1002,6 +1341,7 @@ declare UI: {
   Select: (default: string, choices: { string }, opts: SelectOpts?) -> any,
   Text: (default: string, opts: TextOpts?) -> any,
   Color: (default: string, opts: ColorOpts?) -> any,
+  List: (default: { string }, opts: ListOpts?) -> any,
   Get: (id: string) -> any,
   Set: (id: string, value: any) -> (),
   GetAll: () -> { [string]: any },
@@ -1131,12 +1471,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?,
@@ -1159,7 +1500,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,
@@ -1167,7 +1508,7 @@ declare Net: {
   LocalIP: () -> string?,
 }
 
--- pipe namespace
+-- pipe namespace (permission: exec)
 
 declare Pipe: {
   Open: (name: string, options: { size: number? }?) -> PipeHandle,
@@ -1183,16 +1524,20 @@ declare File: {
   Exists: (path: string) -> boolean,
   Delete: (path: string) -> boolean,
   -- nil path lists the script's own directory. Paths are relative to the
-  -- script dir (the File.* jail); absolute paths are rejected.
+  -- script dir (the File.* jail); absolute paths are rejected. "@data/..."
+  -- paths (3.13.0) reach the script's data folder instead.
   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) -> (),
   ReadJSON: (path: string) -> any,
   WriteJSON: (path: string, value: any) -> (),
   GetScriptDir: () -> string,
+  -- absolute path of the script's data folder (3.13.0); raises for a
+  -- script with no file
+  GetDataDir: () -> string,
   GetSize: (path: string) -> number,
   GetTime: (path: string) -> number,
   IsDir: (path: string) -> boolean,
@@ -1279,6 +1624,7 @@ declare Codec: {
 
 declare Env: {
   Get: (name: string) -> string?,
+  -- Requires the 'exec' permission.
   Set: (name: string, value: string) -> (),
   Home: () -> string?,
   Config: () -> string?,
@@ -1313,6 +1659,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/keys.test.ts

@@ -1,15 +0,0 @@
-import { expect, test } from "bun:test";
-import { normalizeCombo } from "./keys";
-
-test("normalizes every Command spelling models emit", () => {
-  for (const alias of ["LCmd", "Cmd", "Command", "⌘", "Super", "LWin", "Win"]) {
-    expect(normalizeCombo(`${alias}+L`)).toBe("LMeta+L");
-  }
-  expect(normalizeCombo("RCmd+Tab")).toBe("RMeta+Tab");
-});
-
-test("passes through already-valid combos and bare keys", () => {
-  expect(normalizeCombo("LCtrl+Shift+P")).toBe("LCtrl+Shift+P");
-  expect(normalizeCombo("Enter")).toBe("Enter");
-  expect(normalizeCombo(" LMeta + A ")).toBe("LMeta+A");
-});