@rebind.gg/mcp-server 0.3.2 → 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.2",
+  "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",

package/src/index.ts

@@ -18,6 +18,7 @@ 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,
@@ -25,6 +26,7 @@ import {
   KEY_DESC,
   LUA_DOCS_DESC,
   modifierNote,
+  OBSERVE_DOCTRINE,
   type OS,
   openAppHow,
   PROBE_CLIS_CMD,
@@ -310,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}`,
   ]
@@ -1168,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

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

@@ -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?) -> ())?,
@@ -485,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?,
 }
 
@@ -549,10 +559,10 @@ 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",
+  kind: "rect" | "text" | "image",
   x: number?,
   y: number?,
-  -- rect
+  -- rect and image; an image defaults to its size in pixels
   w: number?,
   h: number?,
   fill: string?,
@@ -567,6 +577,9 @@ export type OverlayOp = {
   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
@@ -586,6 +599,8 @@ 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 }?,
 }
 
@@ -601,6 +616,8 @@ export type OverlaySurface = {
 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 & {
@@ -638,6 +655,26 @@ export type OverlayMenu = {
   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: () -> (),
@@ -676,14 +713,132 @@ export type RbOverlay = {
   -- 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 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, scroll and axis, a handler that returns
 -- false swallows the input; for move only with mouse_block=true.
@@ -844,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 },
@@ -966,7 +1122,9 @@ declare rb: {
   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,
@@ -984,6 +1142,9 @@ declare rb: {
     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,
@@ -1068,6 +1229,8 @@ declare rb: {
   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
@@ -1178,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 },
@@ -1360,7 +1524,8 @@ 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; raises when the directory does not exist or cannot be removed.
@@ -1370,6 +1535,9 @@ declare File: {
   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,

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");
-});