@rebind.gg/mcp-server 0.2.0 → 0.2.2

package/README.md

@@ -55,8 +55,8 @@ Connects, takes a capture, and reports the display — the fastest way to catch
 | `type` | Type text into the focused element. |
 | `key` | Press a key or combo, e.g. `Enter`, `LCtrl+L`, `LAlt+Tab`. |
 | `scroll` | Scroll at the cursor. Positive scrolls down, negative up. `unit` is `wheel` (default, fine wheel clicks) or `page` (one PageDown or PageUp per unit, capped at 10). |
-| `read_page` | Extract the focused browser's current page as structured text (URL, forms, interactive elements, plain text) via an address-bar bookmarklet; the full dump, including cleaned HTML, lands in the clipboard. The result is read back through AppleScript (`URL of active tab of front window`), so the relay host must be macOS and the front browser must answer that query. Safari is detected but blocks the bookmarklet path. |
-| `meditate` | Research a problem page until a reasoning model has the data to solve it: fetches the URL directly, pulls the script bundles behind a JS shell so its API endpoints are visible, fetches those endpoints and assets, and reads the live page with vision. 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. |
+| `read_page` | Extract the focused browser's current page as structured text (URL, forms, interactive elements, plain text) via an address-bar bookmarklet; the full dump, including cleaned HTML, lands in the clipboard. The result is read back through AppleScript (`URL of active tab of front window`), so the tool is registered only when the relay host is macOS, and the front browser must answer that query. Safari is detected but blocks the bookmarklet path. |
+| `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`. |
 | `list_displays` / `list_windows` / `focus_window` / `position_window` / `active_window` | Display and window enumeration, focus, and placement. |
@@ -90,7 +90,7 @@ Connects, takes a capture, and reports the display — the fastest way to catch
 
 `meditate` gathers; it does not submit. The intended flow, all gated behind `REBIND_ALLOW_DELEGATION=1`:
 
-1. **`meditate`** → a dossier. Evidence is gathered by **fetching, not by driving the GUI**: a direct GET returns the server's own bytes, and when that comes back a JS shell the script bundles are pulled in so the endpoints the page calls are visible to the model, which then requests them by id. Same-origin URLs are fetched **from inside the page** — the browser's own session, cookies and TLS answer them, so an endpoint that refuses a bare curl responds normally; cross-origin falls back to relay-side curl. The rendered DOM is read when a fetch cannot see the content. It then leaves the browser **open on the problem page** and returns `form` (per-field `{value, source, op}`, traced to evidence) and `submittable`. It never bakes in the captcha — that can rotate, so it is read live at submit time, and its absence does not make a dossier unsubmittable.
+1. **`meditate`** → a dossier. Evidence is gathered by **fetching, not by driving the GUI**: a direct GET returns the server's own bytes, and when that comes back a JS shell the script bundles are pulled in so the endpoints the page calls are visible to the model, which then requests them by id. On a macOS relay, same-origin URLs are fetched **from inside the page** — the browser's own session, cookies and TLS answer them, so an endpoint that refuses a bare curl responds normally; cross-origin falls back to relay-side curl. The rendered DOM is read when a fetch cannot see the content, also on a macOS relay only. It then leaves the browser **open on the problem page** and returns `form` (per-field `{value, source, op}`, traced to evidence) and `submittable`. It never bakes in the captcha — that can rotate, so it is read live at submit time, and its absence does not make a dossier unsubmittable.
 2. **`rebind_versus`** → feed it the dossier to attack the reconciled values before anything irreversible happens.
 3. **Solve (caller-driven, by sight)** on the still-open page: re-navigate to the anchor and confirm the URL; screenshot → click field → type each `form` value; tick attachment checkboxes; read the **live** captcha off the page; then **re-extract the filled form and diff it against the dossier** — on any mismatch or unresolved conflict, stop (do not submit). Only on a clean diff, click submit and verify. When `submittable` is false there is no form to fill; surface the answer instead.
 

package/package.json

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

package/src/index.ts

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { RebindRemote } from "@rebind.gg/client-ts";
 import { z } from "zod";
+import pkg from "../package.json";
 import { mapToImage } from "./coords.ts";
 import { renderScreenshot } from "./image.ts";
 import { normalizeCombo } from "./keys.ts";
@@ -97,8 +98,6 @@ function versusMessages(
 // asked to re-emit the whole growing dossier blows the model's output cap and
 // truncates the JSON; splitting keeps every response small and bounds cost.
 
-/** stop the loop once the model reports at least this much confidence */
-const MEDITATE_CONFIDENT = 0.8;
 /** max distinct pages read (problem page + follows) before the loop must stop */
 const MEDITATE_MAX_PAGES = 10;
 // Budgets sized for a 1M-token context, not a 4k one. These were tight enough
@@ -358,7 +357,7 @@ async function main() {
 
   const { instructions, os } = await buildInstructions(client);
   const server = new McpServer(
-    { name: "rebind", version: "0.1.6" },
+    { name: "rebind", version: pkg.version },
     { instructions },
   );
 
@@ -979,9 +978,10 @@ return { ok = true, proc = proc }
     },
     async ({ handle }) => {
       // handle-based activation can raise without focusing on macOS; fall back
-      // to app-name activation (App.Activate, macOS-only, no-op elsewhere via
-      // pcall). Decided relay-side: this process may run on a different
-      // machine than the relay, so process.platform is the wrong signal.
+      // to app-name activation (App.Activate, pcall-guarded because it raises
+      // where the relay has no App backend). Decided relay-side: this process
+      // may run on a different machine than the relay, so process.platform is
+      // the wrong signal.
       const r = (await client.luaExec(`
 local h = ${handle}
 Window.Activate(h)
@@ -1070,53 +1070,58 @@ return { ok = Window.IsActive(h), name = name }
     async () => text(JSON.stringify(await session.calibrate())),
   );
 
-  register(
-    "read_page",
-    {
-      description:
-        "Extract the CURRENT web page from the focused browser window as structured text — page URL, forms and their fields (with scrollY positions), other interactive elements, and the page's full plain text — and leave the complete dump (including cleaned HTML with absolute links) in the system clipboard. " +
-        "Works in ANY browser: it focuses the address bar via the keyboard and runs a javascript: bookmarklet, so the page must already be loaded and the browser must be the frontmost window (use focus_window first). " +
-        "Far cheaper and more reliable than screenshots for reading page content or finding form fields. Overwrites the clipboard. Safari blocks javascript: URLs — use another browser there.",
-      inputSchema: {
-        html: z
-          .boolean()
-          .default(false)
-          .describe(
-            "include the cleaned-HTML section in the response (always present in the clipboard; often very large)",
-          ),
+  // read_page finds the front app through App.Front and reads its result back
+  // through AppleScript (tabUrl): both exist only on a macOS relay. A failed
+  // OS probe reads as "Windows", so this never offers the tool where it fails.
+  if (os === "macOS") {
+    register(
+      "read_page",
+      {
+        description:
+          "Extract the CURRENT web page from the focused browser window as structured text — page URL, forms and their fields (with scrollY positions), other interactive elements, and the page's full plain text — and leave the complete dump (including cleaned HTML with absolute links) in the system clipboard. " +
+          "It focuses the address bar via the keyboard and runs a javascript: bookmarklet, so the page must already be loaded and the browser must be the frontmost window (use focus_window first). The result is read back through AppleScript, so the front browser must answer the active-tab URL query. " +
+          "Far cheaper and more reliable than screenshots for reading page content or finding form fields. Overwrites the clipboard. Safari blocks javascript: URLs — use another browser there.",
+        inputSchema: {
+          html: z
+            .boolean()
+            .default(false)
+            .describe(
+              "include the cleaned-HTML section in the response (always present in the clipboard; often very large)",
+            ),
+        },
       },
-    },
-    async ({ html }) => {
-      // Target whichever browser is actually in front, and remember the page we
-      // are on: a dropped paste sends Enter to search and navigates away, so the
-      // retry has to be able to put the user back where they were.
-      const front = await frontApp();
-      const app = BROWSER_RE.test(front) ? front : undefined;
-      const here = app ? await tabUrl(app) : "";
-      const clip = await extractPage(app, here || undefined);
-      if (!clip) {
-        return text(
-          "WARNING: page extraction did not complete — the parsed page never arrived. " +
-            "Likely causes: the focused window is not a browser, the page blocks javascript: URLs (strict CSP, browser start page, or Safari), or the page is still loading. " +
-            "Take a screenshot to check state, then retry.",
-        );
-      }
-      const cut = clip.indexOf("\n\n=== Cleaned HTML");
-      let body = html || cut === -1 ? clip : clip.slice(0, cut);
-      const notes: string[] = [];
-      if (!html && cut !== -1)
-        notes.push(
-          "[cleaned HTML omitted — the full dump is in the clipboard; pass html=true to include it]",
-        );
-      if (body.length > 60_000) {
-        body = body.slice(0, 60_000);
-        notes.push(
-          "[truncated at 60000 chars — the full dump is in the clipboard]",
-        );
-      }
-      return text(notes.length ? `${body}\n\n${notes.join("\n")}` : body);
-    },
-  );
+      async ({ html }) => {
+        // Target whichever browser is actually in front, and remember the page we
+        // are on: a dropped paste sends Enter to search and navigates away, so the
+        // retry has to be able to put the user back where they were.
+        const front = await frontApp();
+        const app = BROWSER_RE.test(front) ? front : undefined;
+        const here = app ? await tabUrl(app) : "";
+        const clip = await extractPage(app, here || undefined);
+        if (!clip) {
+          return text(
+            "WARNING: page extraction did not complete — the parsed page never arrived. " +
+              "Likely causes: the focused window is not a browser, the page blocks javascript: URLs (strict CSP, browser start page, or Safari), or the page is still loading. " +
+              "Take a screenshot to check state, then retry.",
+          );
+        }
+        const cut = clip.indexOf("\n\n=== Cleaned HTML");
+        let body = html || cut === -1 ? clip : clip.slice(0, cut);
+        const notes: string[] = [];
+        if (!html && cut !== -1)
+          notes.push(
+            "[cleaned HTML omitted — the full dump is in the clipboard; pass html=true to include it]",
+          );
+        if (body.length > 60_000) {
+          body = body.slice(0, 60_000);
+          notes.push(
+            "[truncated at 60000 chars — the full dump is in the clipboard]",
+          );
+        }
+        return text(notes.length ? `${body}\n\n${notes.join("\n")}` : body);
+      },
+    );
+  }
 
   register(
     "run_lua",
@@ -1283,9 +1288,9 @@ return { ok = Window.IsActive(h), name = name }
       "meditate",
       {
         description:
-          "Research a problem page until enough data is collected to solve it. Fetches `url` directly (relay-side curl) and, when the response is a JS shell, pulls its script bundles so the API endpoints behind the page are visible; falls back to extracting the rendered page in a browser when a fetch cannot see the content. A reasoning model then iterates: identify the problem, fetch the URLs and API endpoints that close information gaps, download required assets, until it reaches confidence >= 0.8, has nothing left to fetch, or hits max_rounds. A final pass renders everything into a solving dossier. " +
+          "Research a problem page until enough data is collected to solve it. Fetches `url` directly (relay-side curl) and, when the response is a JS shell, pulls its script bundles so the API endpoints behind the page are visible; falls back to extracting the rendered page in a browser when a fetch cannot see the content. A reasoning model then iterates: identify the problem, fetch the URLs and API endpoints that close information gaps, download required assets, until it has nothing left to fetch or hits max_rounds. A final pass renders everything into a solving dossier. " +
           "Returns the dossier as markdown plus a JSON plan {error, problem, requirements, plan, confidence, sources, assets, pending_fetch, notes, cost_usd}. `error` is non-null (with the partial data still returned, never thrown) when no clear problem is identifiable or the browser could not be driven. Downloaded `assets` paths are on the RELAY host. " +
-          "Drives the real browser (takes over keyboard/clipboard for the duration) and spends OpenRouter credits. Refuses non-public URLs (loopback/private/link-local). Safari cannot be driven — pass `browser` to name another.",
+          "On a macOS relay it also drives the real browser (takes over keyboard/clipboard for the duration) to render a JS shell, fetch same-origin URLs through the page, and read the live captcha; elsewhere it reads pages over HTTP only. Spends OpenRouter credits. Refuses non-public URLs (loopback/private/link-local). Safari cannot be driven — pass `browser` to name another.",
         inputSchema: {
           url: z.string().url().describe("page that explains the problem"),
           goal: z
@@ -1467,20 +1472,25 @@ return { ok = Window.IsActive(h), name = name }
           // evidence. The per-page budget keeps only the FIRST chars, so the
           // highest-signal content has to come first.
           let first = isShell ? null : raw;
-          // Always wait for the browser and place the window, whatever the fetch
-          // returned. The page is left open for the vision pass and for whoever
-          // solves it by sight afterwards, so a predictable window rect is not
-          // specific to the render path — it is the point of opening a browser
-          // at all. Positioning only when a fetch happened to come back thin
-          // left the solver working against an arbitrarily sized window.
+          // Where the browser can be driven, always wait for it and place the
+          // window, whatever the fetch returned. The page is left open for the
+          // vision pass and for whoever solves it by sight afterwards, so a
+          // predictable window rect is not specific to the render path — it is
+          // the point of opening a browser at all. Positioning only when a
+          // fetch happened to come back thin left the solver working against
+          // an arbitrarily sized window. Driving the browser needs App.Front
+          // and the AppleScript readback, which exist only on a macOS relay;
+          // elsewhere the run stays on HTTP.
+          const drive = os === "macOS";
           let front = "";
-          for (let i = 0; i < 12; i++) {
+          for (let i = 0; drive && i < 12; i++) {
             await sleep(700);
             front = await frontApp();
             if (BROWSER_RE.test(front)) break;
           }
           const haveBrowser = BROWSER_RE.test(front);
-          if (!haveBrowser)
+          if (!drive) note("browser steps skipped: they need a macOS relay");
+          else if (!haveBrowser)
             note(
               browser
                 ? `browser "${browser}" never reached the foreground (front app: ${front || "unknown"}) — is it installed under that exact name? try the default browser or a different name`
@@ -1509,7 +1519,9 @@ return { ok = Window.IsActive(h), name = name }
               null,
               haveBrowser
                 ? "could not read the problem page — the fetch returned nothing and the rendered page could not be extracted"
-                : `could not read the problem page — it is a JS shell needing a browser to render, but none launched${browser ? ` (requested "${browser}")` : ""}. Start the browser, or pass a browser name that is installed`,
+                : !drive
+                  ? "could not read the problem page: the fetch returned nothing, and rendering it needs a browser driven on a macOS relay"
+                  : `could not read the problem page — it is a JS shell needing a browser to render, but none launched${browser ? ` (requested "${browser}")` : ""}. Start the browser, or pass a browser name that is installed`,
             );
           pages.push({ url: pageUrl, dump: trimDump(first) });
           seen.add(normUrl(pageUrl));
@@ -1623,7 +1635,11 @@ return { ok = Window.IsActive(h), name = name }
                 return false;
               }
             });
-            const fetched = await pageFetch(sameOrigin, browser, pageUrl);
+            const fetched = await pageFetch(
+              drive ? sameOrigin : [],
+              browser,
+              pageUrl,
+            );
             for (const u of todo) {
               const viaPage = fetched[u];
               const body =
@@ -1641,37 +1657,40 @@ return { ok = Window.IsActive(h), name = name }
           // 4. revisit the anchor so the browser is left on the form page for
           // the solver, and run an ISOLATED vision pass to confirm the form and
           // read the live captcha. Its failure must never sink the dossier.
-          await gotoUrl(pageUrl);
-          try {
-            const shot = await captureScreen();
-            const vstep = await llmStep(
-              [
-                { role: "system", content: MEDITATE_VISION_SYS },
-                {
-                  role: "user",
-                  content: [
-                    { type: "text", text: "Read this page." },
-                    { type: "image_url", image_url: { url: shot.dataUrl } },
-                  ],
-                },
-              ],
-              [],
-              VISION_MODEL || model_,
-            );
-            cost += vstep.usage?.cost ?? 0;
-            const vr = parseJsonObject<VisionRead>(
-              String(vstep.message.content ?? ""),
-            );
-            if (vr) {
-              liveCaptcha = vr.captcha_text ?? null;
+          // Both need the live page, so they run only when a browser was driven.
+          if (haveBrowser) {
+            await gotoUrl(pageUrl);
+            try {
+              const shot = await captureScreen();
+              const vstep = await llmStep(
+                [
+                  { role: "system", content: MEDITATE_VISION_SYS },
+                  {
+                    role: "user",
+                    content: [
+                      { type: "text", text: "Read this page." },
+                      { type: "image_url", image_url: { url: shot.dataUrl } },
+                    ],
+                  },
+                ],
+                [],
+                VISION_MODEL || model_,
+              );
+              cost += vstep.usage?.cost ?? 0;
+              const vr = parseJsonObject<VisionRead>(
+                String(vstep.message.content ?? ""),
+              );
+              if (vr) {
+                liveCaptcha = vr.captcha_text ?? null;
+                note(
+                  `vision: has_form=${!!vr.has_form} captcha=${!!vr.captcha_present}${vr.notes ? ` — ${vr.notes}` : ""}`,
+                );
+              }
+            } catch (e) {
               note(
-                `vision: has_form=${!!vr.has_form} captcha=${!!vr.captcha_present}${vr.notes ? ` — ${vr.notes}` : ""}`,
+                `vision pass skipped (model may lack image input): ${e instanceof Error ? e.message : e}`,
               );
             }
-          } catch (e) {
-            note(
-              `vision pass skipped (model may lack image input): ${e instanceof Error ? e.message : e}`,
-            );
           }
 
           // 5. one final text call turns everything gathered into the dossier

package/src/prompts.ts

@@ -85,7 +85,7 @@ export const RUN_LUA_DESC =
   "The chunk runs ONCE and must end with `return <value>`: script hooks (OnDown/OnTick) never fire here, and coroutine-only calls " +
   '(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. " +
+  '(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. " +
   '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. " +

package/src/rebind.d.luau

@@ -35,6 +35,14 @@ export type ServerHandle = {
   Stop: (self: ServerHandle) -> (),
 }
 
+-- UDP: socket handle returned by Net.UDPListen. SendTo sends from the bound
+-- address and returns false when the send fails or the socket is stopped.
+export type UdpHandle = {
+  port: number,
+  SendTo: (self: UdpHandle, ip: string, port: number, bytes: string) -> boolean,
+  Stop: (self: UdpHandle) -> (),
+}
+
 -- WebSocket: server-side per-connection handle passed to OnConnect/OnMessage/OnClose.
 -- `id` is a monotonic identifier unique to this connection.
 export type WsClient = {
@@ -112,6 +120,19 @@ export type WindowPos = {
   height: number,
 }
 
+-- the input device a key, button, move or scroll came from. hooks get nil
+-- where the source cannot tell devices apart (Windows and macOS software mode)
+export type InputDevice = {
+  id: string,
+  name: string,
+  nickname: string?,
+  kind: "keyboard" | "mouse" | "other",
+  vid: string,
+  pid: string,
+  source: "vm" | "host",
+  exact: boolean,
+}
+
 export type MousePos = {
   x: number,
   y: number,
@@ -224,9 +245,10 @@ export type UiProxy = { [string]: any }
 
 -- bind config for table-style binding
 export type BindConfig = {
-  when: (() -> boolean)?,
-  action: (() -> boolean?)?,
-  release: (() -> ())?,
+  device: string?, -- nickname or id: the bind answers only to that device
+  when: ((device: InputDevice?) -> boolean)?,
+  action: ((device: InputDevice?) -> boolean?)?,
+  release: ((device: InputDevice?) -> ())?,
 }
 
 -- runtime identity table
@@ -300,6 +322,20 @@ 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) -> (),
@@ -319,6 +355,15 @@ declare HID: {
   Scroll: (amount: number) -> (),
   SetMouseMode: (mode: string) -> (),
   GetMouseMode: () -> 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?,
+  -- 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.
+  Joypad: (state: JoypadState?) -> (),
+  -- back to neutral; the relay also does this when a script stops or errors
+  JoypadReset: () -> (),
 }
 
 -- input namespace
@@ -354,7 +399,7 @@ declare Bind: typeof(setmetatable({} :: {
   Toggle: (key: string, uiId: string) -> BindHandle,
   Remap: (from: string, to: string) -> BindHandle,
 }, {} :: {
-  __call: (self: any, key: string, config: (() -> boolean?) | BindConfig) -> BindHandle,
+  __call: (self: any, key: string, config: ((device: InputDevice?) -> boolean?) | BindConfig) -> BindHandle,
 }))
 
 -- timer namespace
@@ -374,6 +419,9 @@ declare Macro: {
   StopAll: () -> (),
   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.
+  ToScript: (macro: { MacroAction }, name: string) -> string,
   Stream: (macro: { MacroAction }) -> (),
   Abort: () -> (),
 }
@@ -517,9 +565,12 @@ declare Window: {
 }
 
 -- app namespace: application-level control (Keyboard Maestro's Application
--- Control). names match case-insensitively by app display name. Front/IsRunning/
--- Activate are permission-free; Hide/Quit/IsHidden drive an AppleEvent and
--- prompt for macOS Automation permission on first use.
+-- 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.
+-- 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.
 
 export type AppInfo = {
   name: string,
@@ -549,6 +600,10 @@ declare Net: {
   Listen: (port: number, handler: (request: HttpRequest) -> HttpResponseSpec | string) -> ServerHandle,
   WSListen: (port: number, handlers: WsListenHandlers) -> 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,
+  -- this computer's IPv4 address on its default route, or nil when there is none.
+  LocalIP: () -> string?,
 }
 
 -- pipe namespace
@@ -750,14 +805,14 @@ declare Registry: {
 -- declare function OnFocus(window: WindowInfo): ()
 -- declare function OnBlur(window: WindowInfo): ()
 -- declare function OnTick(dtMs: number): ()  -- ms elapsed since the previous OnTick (0 on the first)
--- declare function OnDown(key: string): boolean?
--- declare function OnUp(key: string, durationMs: number): boolean?
--- declare function OnMove(dx: number, dy: number): boolean?  -- return value only used with mouse_block=true (hardware mode only)
--- declare function OnScroll(delta: number): boolean?
+-- declare function OnDown(key: string, device: InputDevice?): boolean?
+-- declare function OnUp(key: string, durationMs: number, device: InputDevice?): boolean?
+-- 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 OnInputDown(key: string): ()
--- declare function OnInputUp(key: string, durationMs: number): ()
--- declare function OnInputMove(dx: number, dy: number): ()
--- declare function OnInputScroll(delta: number): ()
+-- 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?): ()
+-- declare function OnInputScroll(delta: number, device: InputDevice?): ()
 -- declare function OnError(message: string): ()
 -- declare function OnReload(): ()