ispyx 0.0.0-stage → 1.0.0

package/src/macos-entry.js

@@ -0,0 +1,16 @@
+// Entry point used by Ispyx.app: the app starts it as the resident (`--resident`), and the MCP launcher
+// (Contents/Resources/ispyx) as the thin forwarder (`mcp`). Picks the platform automatically (darwin), whatever the
+// environment of the MCP client says, then runs the normal server.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+delete process.env.ISPYX_PLATFORM;
+// The app's resident and every forwarder meet on one socket in the app's data folder, whatever their environment
+// (an MCP client may give its children another temp directory).
+if (!process.env.ISPYX_PIPE) {
+  const dir = path.join(os.homedir(), 'Library', 'Application Support', 'Ispyx');
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* reported when listening fails */ }
+  process.env.ISPYX_PIPE = path.join(dir, 'ispyx.sock');
+}
+await import('./core/server.js');

package/src/platform/CONTRACT.md

@@ -0,0 +1,131 @@
+# Platform contract
+
+`src/platform/index.js` loads one folder (`win32/`, `darwin/`, `linux/`, or `fake/` when `ISPYX_PLATFORM=fake`) and
+exports its module namespace as the default export. Everything under `src/core/` and `src/effects/` talks to the OS
+only through that namespace (`import platform from '../platform/index.js'`). A platform folder's `index.js` must
+export everything below. The Windows implementation (`win32/`) is the reference: when this document is unclear,
+read it.
+
+## Conventions
+
+- **Calls are synchronous** unless marked `async`. (`darwin/` reaches a native helper process, see
+  `darwin/PROTOCOL.md`; it makes the calls look synchronous.)
+- **Coordinates** are integers in the platform's *logical desktop space*, origin top-left of the primary monitor,
+  y down; other monitors may have negative values. On Windows they are physical pixels (the process is
+  per-monitor DPI aware). On macOS they are **points** (not Retina pixels); captures are returned at that logical
+  size too (downscaled from the physical image), so `rect.width` always equals `bits` width.
+- **Window ids** (`hwnd` in the tool API) are positive integers, opaque to the core: Windows `HWND`, macOS
+  `CGWindowID`. `0` means "none".
+- **Key codes** are opaque to the core. `parseChord` turns `"ctrl+shift+t"` into an array of platform key codes and
+  the core only hands that array back to `keysDown`, `keysUp`, `pressVirtualKeys`, `chordDown`, `insertsContent`.
+- **Errors**: throw `Error` with a message meant for the AI caller (plain sentence, says what to do). The core
+  turns it into a tool error.
+- **Pixel buffers** are `Uint8Array`, BGRA, premultiplied alpha, top-down, `width * height * 4` bytes.
+
+## Lifecycle
+
+| Export | Signature | Notes |
+|---|---|---|
+| `name` | `'win32' \| 'darwin' \| 'linux' \| 'fake'` | |
+| `capabilities` | `{ elevation: boolean }` | `elevation:false` removes the "elevated window" concept (macOS). |
+| `stopLabel` | `string` | Shown to the user: `'Alt+Esc'` on Windows, `'Option+Esc'` on macOS. |
+| `init()` | `() => void` | Idempotent. Windows: per-monitor DPI awareness, 1 ms timer. macOS: connect to the helper and check permissions; throw a helpful error naming the missing permission. |
+| `dataDir()` | `() => string` | Per-user writable directory (password hash). |
+| `sleep(ms)` | `=> Promise` | |
+
+## Windows, monitors, pointer
+
+| Export | Returns |
+|---|---|
+| `listWindows({ includeUntitled })` | `describeWindow` objects of visible, on-screen windows, front to back where the OS gives an order. |
+| `describeWindow(id)` | `{ hwnd, title, className, pid, process, elevated, minimized, rect }`. `className` may be `''`. `process` is the executable name (Windows `notepad.exe`; macOS the app's executable name, e.g. `Notes`) and is what the denylist matches. `elevated` is `false` where the concept does not exist. |
+| `getRect(id)` | `{ left, top, width, height } \| null` |
+| `getTitle(id)`, `getClass(id)`, `getPid(id)` | strings / number |
+| `processInfo(pid)` | `{ name, elevated }` |
+| `windowExists(id)` | boolean |
+| `rootWindowAt(x, y)` | id of the top-level window under the point, `0` if none |
+| `foregroundWindow()` | id of the focused top-level window, `0` if none |
+| `bringToForeground(id)` | `async`, resolves true when the window is in front (un-minimises first) |
+| `windowDpi(id)` | number (96 = 100 %); macOS returns 96 |
+| `selfIsElevated()` | boolean (`false` on macOS) |
+| `isScreenLocked()` | boolean: no input possible (lock screen, secure desktop) |
+| `focusIsPassword()` | boolean: the focused control is a password field |
+| `foregroundLayout()` | number identifying the active keyboard layout (reported as hex; `0` if unknown) |
+| `virtualScreen()` | `{ x, y, width, height }` bounding box of all monitors |
+| `listMonitors()` | `[{ left, top, width, height, primary }]` |
+| `cursorPos()` | `{ x, y }` |
+
+## Input
+
+| Export | Notes |
+|---|---|
+| `mouseMoveTo(x, y)` | Absolute, instant (smoothing is done by the core). |
+| `mouseDown(button)`, `mouseUp(button)` | `'left' \| 'right' \| 'middle'`. |
+| `mouseWheel(notches)` | Positive = scroll up. Fractions allowed (smooth scrolling). |
+| `mouseHWheel(notches)` | Positive = scroll right. |
+| `typeUnicode(text, check, delays)` | `async`. Types `text` one character at a time as Unicode (layout independent). Before each character call `check()` (it may throw to cancel); after it wait `delays[i]` ms. Returns when done. |
+| `keysDown(codes)`, `keysUp(codes)` | Hold / release key codes (array). |
+| `pressVirtualKeys(codes)` | Press the chord (down in order, up in reverse). |
+| `parseChord(str)` | `"ctrl+a"` -> codes. Names: `ctrl shift alt enter esc tab space backspace delete home end pageup pagedown left up right down f1..f24 a-z 0-9` and punctuation `, . - = / ; ' [ ] \ \``. `win`, `cmd`, `meta`, `super` mean the OS key (Windows key / Command). `alt` is Alt / Option. |
+| `parseSequence(str)` | `"ctrl+a ctrl+c"` -> array of code arrays. |
+| `insertsContent(codes)` | True for chords that paste (must not go into a password field). |
+
+## Screen capture
+
+| Export | Returns |
+|---|---|
+| `captureScreenRect({ left, top, width, height })` | `{ bits, width, height, rect }`; `rect` is the area actually captured. |
+| `captureWindow(id)` | `{ bits, width, height, rect, method }`; works for covered windows where the OS allows it, otherwise requires the window to be in front and throws a message saying so. |
+
+## Clipboard
+
+`getClipboardText()` -> `{ text: string \| null, formats: string[] }`; `setClipboardText(text)`;
+`setClipboardFile(path)` (puts a file reference, as if copied in the file manager).
+
+## Stop hotkey
+
+| Export | Notes |
+|---|---|
+| `chordDown(codes)` | True while every key of the chord is physically down (used for polling). |
+| `installStopHotkey(onStop, lingerMs)` | Returns `{ touch(), active, stop() }`. A keyboard hook for the stop chord (`Alt+Esc`; macOS `Option+Esc`) that exists only while `touch()` was called in the last `lingerMs` (default 30 000 ms): no hook while idle. The hook swallows the chord and calls `onStop('Alt+Esc')` once per press (auto-repeat counts as one). Injected (synthetic) key events must be ignored. |
+
+## UI
+
+| Export | Notes |
+|---|---|
+| `Overlay` | The "working / stopped / cancelled" banner. `new Overlay({ enabled, hideAfterMs, stopLabel })` with `begin(label)`, `done()`, `stop(reason)`, `cancel(reason, windowMs)`, `active`, `async hiddenDuring(fn)` (hides the banner while `fn` runs, e.g. during a screenshot). Always-on-top, click-through, never takes focus, covers no more than a thin bar. |
+| `showDialog(opts, ms)` | `async`. The native password window for the auth gate. `opts = { mode: 'setup' \| 'unlock', message, value, unit }`; resolves to `{ password, confirm, value, unit, makeDefault }` or `{ cancel: true, reason }` where reason is `'timed out'`, `'closed by the user'` or `'dialog failed: ...'`. Must come to the front and close itself after `ms`. |
+| `Layer` | Effect window: see below. |
+| `textMask(text, heightPx, weight)` | `{ width, height, mask }`: anti-aliased coverage mask (0-255 per pixel) of `text` in the platform UI font. |
+| `ensurePump()` | Windows only (message pump); other platforms export a no-op. |
+
+### `Layer`
+
+A borderless, click-through, never-focused, always-on-top window showing a pixel buffer with per-pixel alpha. Used by
+all effects (`src/effects/`).
+
+```js
+const layer = new Layer(width, height);   // not visible yet
+layer.px                                  // Uint8Array(width*height*4), BGRA premultiplied; draw into it
+layer.present(x, y, alpha, height?, width?, srcY?) // move to (x,y), show the top-left width x height part of the
+                                          // buffer starting at row srcY, with constant opacity alpha 0..255
+layer.shown                               // true after the first present()
+layer.destroy()                           // hide and free
+```
+
+`present` is called up to 60 times a second per layer; layers can be as large as the whole desktop (5760 x 1080).
+
+## Effects renderer is shared
+
+`src/effects/` holds all drawing code (eye, scan line, rings, pills, radar) as pure JavaScript writing into
+`layer.px`. A platform only provides `Layer` and `textMask`. Do not add effect-specific code to a platform folder.
+
+## win32-only optional exports
+
+Other platforms may lack these; callers must feature-test (`if (platform.Tray)`).
+
+- `Tray({ tooltip, onOpen, onQuit, getStatus })`: notification-area eye icon on the shared message pump. Menu: status line
+  (from `getStatus()`, refreshed on each open), Open (default; also left click),
+  Quit. Methods: `setTooltip(s)`, `destroy()`. Re-adds itself when Explorer restarts. Callbacks never throw into the host.
+- `autostart` `{ get(), set(on), command() }`: per-user HKCU Run entry `Ispyx` that starts `src/server.js` hidden
+  via `wscript.exe` + `%APPDATA%\ispyx\start.vbs`. `ISPYX_AUTOSTART_VALUE` overrides the value name (tests).

package/src/platform/darwin/PROTOCOL.md

@@ -0,0 +1,82 @@
+# macOS helper protocol
+
+On macOS the platform calls are made by **Ispyx.app** (`native/macos/`), a signed menu-bar app that holds the
+Accessibility and Screen Recording permissions. The Node side (`src/platform/darwin/`) is a thin client. The
+contract it implements is `../CONTRACT.md`.
+
+## Process model
+
+```
+Claude / MCP client --stdio--> `ispyx mcp` (Contents/Resources/ispyx: thin forwarder, one per client)
+                                   |  ispyx.sock (src/core/ipc.js pipe, pinned by macos-entry.js)
+                                   v
+              resident Node core (`--resident`, started and watched by Ispyx.app) --helper.sock--> Ispyx.app (Swift,
+                                                                               the only process that touches the OS)
+```
+
+- Ispyx.app runs once per user (menu-bar agent, `LSUIElement`). At launch it starts the bundled Node core as the
+  resident (`ResidentService.swift`), the one process that does the work (like the tray app on Windows, see
+  `src/core/RESIDENT.md`), and starts it again if it dies. The panel's activity and settings come from it, so they
+  work without any AI app connected.
+- `ispyx mcp` forwards every call to the resident; when none answers it opens the app (`open -g <the app>`), which
+  starts one, and waits.
+- Quitting the app stops the resident with SIGTERM, which tells the forwarders to exit first. A resident whose app is
+  gone (`ISPYX_APP_PID`) leaves by itself and never opens the app again.
+- Socket: `~/Library/Application Support/Ispyx/helper.sock` (unix domain socket, mode 0600).
+- The app never listens on a network port.
+
+## Wire format
+
+UTF-8 JSON lines (`\n`-terminated), one object per line, both directions. Binary payloads (pixels, masks) are
+**not** in JSON: they travel in shared files, see "Shared pixel buffers".
+
+Request: `{ "id": 17, "fn": "listWindows", "args": [ { "includeUntitled": false } ] }`
+Response: `{ "id": 17, "ok": true, "result": ... }` or `{ "id": 17, "ok": false, "error": "message for the AI" }`.
+
+Responses may come out of order; `id` pairs them. Events from the app (no `id`):
+`{ "event": "stop", "reason": "Option+Esc" }` (stop hotkey pressed), `{ "event": "permissions", "missing": ["accessibility"] }`.
+
+The Ispyx window asks the server for its part of the panel (activity, effects, password, denylist):
+`{ "event": "panelRequest", "req": 3, "kind": "state" | "action", "name": "setEffects", "value": false }`. The owner
+answers with the call `panelReply({ "req": 3, "ok": true, "result": ... })` or `{ "req": 3, "ok": false, "error": "..." }`
+(`panel.js`); the app takes the first answer and gives up after a timeout. Events never carry an `id` key.
+
+### Functions
+
+Every function of `../CONTRACT.md` that is not pure JavaScript has the same name here, with `args` = the call's
+arguments and `result` = the return value, JSON-encoded. Differences:
+
+- `captureScreenRect(rect)` / `captureWindow(id)`: result is `{ file, width, height, rect, method }` where `file` is
+  a path to a raw BGRA file (`width*height*4` bytes) in `$TMPDIR/ispyx/`; the client reads it, then the app
+  deletes it. (Files stay small: captured at logical size.)
+- `typeUnicode`: the client loops, calling `typeChar(codePoint)` per character (the delays and `check()` stay in JS). `codePoint` 10 (newline) means the Return key; carriage
+  returns are dropped by the client.
+- `parseChord`, `parseSequence`, `insertsContent`, `chordDown` (keys table): client side; `chordDown(codes)` calls
+  `keysState(codes)` -> `boolean` (all down).
+- `installStopHotkey`: the client calls `hookTouch(lingerMs)` / `hookStop()`; the app installs a `CGEventTap`
+  (active, to swallow the chord) only while touched and emits the `stop` event.
+- Overlay: `overlayShow({ text, kind })`, `overlayHide()`, `overlayVisible()`; the JS `Overlay` class holds the timers
+  and texts exactly like the Windows one.
+- `showDialog(opts, ms)`: runs the native dialog in the app, result as in the contract.
+
+### Layers (effect windows)
+
+`layerCreate({ width, height })` -> `{ layer: <int>, file: <path> }`. The app creates a file
+`$TMPDIR/ispyx/layer-<n>.bgra` of `width*height*4` bytes and memory-maps it; the client maps the same file
+(`mmap` through `koffi`) and exposes it as `layer.px`. No pixel data goes over the socket.
+`layerPresent({ layer, x, y, alpha, height, width, srcY })` -> `true`: show that part of the buffer in the layer's
+window (`NSPanel`, `.screenSaver` level, `ignoresMouseEvents`, not key, not main, joins all spaces). Coordinates are
+the contract's logical desktop space; convert to AppKit's bottom-left origin inside the app.
+`layerDestroy({ layer })`. `textMask({ text, heightPx, weight })` -> `{ width, height, file }` (one byte per pixel).
+
+## Latency budget
+
+The client makes calls look synchronous (`Atomics.wait` on a worker that owns the socket). A round trip must stay
+under 1 ms for `mouseMoveTo`, `cursorPos` and `layerPresent`: the core calls them 60-100 times a second.
+
+## Permissions
+
+On the first call the app checks `AXIsProcessTrusted()` and `CGPreflightScreenCaptureAccess()`. When one is
+missing, every function that needs it fails with a message such as `Ispyx needs the Accessibility permission. Open
+System Settings > Privacy & Security > Accessibility and switch Ispyx on, then try again.` and the app shows its
+onboarding window.

package/src/platform/darwin/hotkey.js

@@ -0,0 +1,41 @@
+// Emergency stop hotkey (Option+Esc). The CGEventTap lives in Ispyx.app and exists only while touched.
+import { callSync, post, onEvent } from './rpc.js';
+
+export const HOOK_LINGER_MS = 30000;
+
+/** True while every key of the chord is physically down right now. */
+export const chordDown = (codes) => callSync('keysState', codes) === true;
+
+/**
+ * Same shape as the Windows hook: touch() arms the app's event tap and pushes its removal lingerMs ahead; the
+ * app emits a `stop` event per press (auto-repeat counts as one, synthetic events are ignored there).
+ */
+export function installStopHotkey(onStop, lingerMs = HOOK_LINGER_MS) {
+  let armed = false;
+  let timer = null;
+  let off = null;
+  const expire = () => {
+    timer = null;
+    armed = false;
+  };
+  const stop = () => {
+    if (timer) clearTimeout(timer);
+    expire();
+    if (off) { off(); off = null; }
+    try { post('hookStop'); } catch { /* app gone */ }
+  };
+  return {
+    touch() {
+      if (!armed) {
+        armed = true;
+        off ??= onEvent('stop', (ev) => { if (armed) onStop(ev?.reason ?? 'Option+Esc'); });
+      }
+      post('hookTouch', lingerMs);
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(expire, lingerMs);
+      timer.unref();
+    },
+    active: () => armed,
+    stop,
+  };
+}

package/src/platform/darwin/index.js

@@ -0,0 +1,118 @@
+// macOS platform layer: the API every platform exports (see ../CONTRACT.md), implemented by forwarding to
+// Ispyx.app over its unix socket (see PROTOCOL.md). Nothing here touches the OS directly.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { callSync, callAsync } from './rpc.js';
+
+export { chordDown, installStopHotkey, HOOK_LINGER_MS } from './hotkey.js';
+export { Overlay } from './overlay.js';
+export { parseChord, parseSequence, insertsContent } from './keys.js';
+export { Layer, textMask } from './layer.js';
+export { onEvent } from './rpc.js';
+export { servePanel } from './panel.js';
+
+export const name = 'darwin';
+export const capabilities = { elevation: false };
+export const stopLabel = 'Option+Esc';
+
+export const dataDir = () => path.join(os.homedir(), 'Library', 'Application Support', 'Ispyx');
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const ensurePump = () => {};
+export const pumpOnce = () => {};
+
+let initialised = false;
+/** Connects to the app (starting it if needed). foregroundWindow needs Accessibility, so a missing permission surfaces here. */
+export function init() {
+  if (initialised) return;
+  callSync('foregroundWindow');
+  initialised = true;
+}
+
+// ---------- windows, monitors, pointer ----------
+
+export const listWindows = (opts = {}) => callSync('listWindows', { includeUntitled: false, ...opts });
+export const describeWindow = (id) => callSync('describeWindow', id);
+export const getRect = (id) => callSync('getRect', id);
+export const getTitle = (id) => callSync('getTitle', id);
+export const getClass = (id) => callSync('getClass', id);
+export const getPid = (id) => callSync('getPid', id);
+export const processInfo = (pid) => callSync('processInfo', pid);
+export const windowExists = (id) => !!id && callSync('windowExists', id) === true;
+export const rootWindowAt = (x, y) => callSync('rootWindowAt', x, y);
+export const foregroundWindow = () => callSync('foregroundWindow');
+export const bringToForeground = (id) => callAsync('bringToForeground', id);
+export const windowDpi = (id) => callSync('windowDpi', id);
+export const selfIsElevated = () => false;
+export const isScreenLocked = () => callSync('isScreenLocked') === true;
+export const focusIsPassword = () => callSync('focusIsPassword') === true;
+export const foregroundLayout = () => callSync('foregroundLayout');
+export const virtualScreen = () => callSync('virtualScreen');
+export const listMonitors = () => callSync('listMonitors');
+export const cursorPos = () => callSync('cursorPos');
+
+// ---------- input ----------
+
+export const mouseMoveTo = (x, y) => { callSync('mouseMoveTo', x, y); };
+export const mouseDown = (button = 'left') => { callSync('mouseDown', button); };
+export const mouseUp = (button = 'left') => { callSync('mouseUp', button); };
+export const mouseWheel = (notches) => { callSync('mouseWheel', notches); };
+export const mouseHWheel = (notches) => { callSync('mouseHWheel', notches); };
+export const keysDown = (codes) => { callSync('keysDown', codes); };
+export const keysUp = (codes) => { callSync('keysUp', codes); };
+export const pressVirtualKeys = (codes) => { callSync('pressVirtualKeys', codes); };
+
+/**
+ * One character at a time with a pause after each (delays[i] ms, never under 8 ms), like a person typing; the
+ * same loop as the Windows one. The app types each code point with typeChar (10 = Return; CR is skipped).
+ */
+export async function typeUnicode(text, check, delays) {
+  let i = 0;
+  for (const ch of text) {
+    if (ch === '\r') { i++; continue; }
+    check?.();
+    await callAsync('typeChar', ch.codePointAt(0));
+    await sleep(Math.max(8, delays?.[i++] ?? 8));
+  }
+}
+
+// ---------- capture ----------
+
+function readCapture(r) {
+  const need = r.width * r.height * 4;
+  let data;
+  try {
+    data = fs.readFileSync(r.file);
+  } catch (e) {
+    throw new Error(`Could not read the capture file from Ispyx (${e.code ?? e.message}).`);
+  }
+  try { fs.unlinkSync(r.file); } catch { /* already gone */ }
+  if (data.length < need) throw new Error(`The capture file is too short (${data.length} of ${need} bytes).`);
+  return new Uint8Array(data.buffer, data.byteOffset, need);
+}
+
+export function captureScreenRect(rect) {
+  const r = callSync('captureScreenRect', rect);
+  return { bits: readCapture(r), width: r.width, height: r.height, rect: r.rect };
+}
+
+export function captureWindow(id) {
+  const r = callSync('captureWindow', id);
+  return { bits: readCapture(r), width: r.width, height: r.height, rect: r.rect, method: r.method };
+}
+
+// ---------- clipboard ----------
+
+export const getClipboardText = () => callSync('getClipboardText');
+export const setClipboardText = (text) => { callSync('setClipboardText', text); };
+export const setClipboardFile = (file) => { callSync('setClipboardFile', file); };
+
+// ---------- dialog ----------
+
+export async function showDialog(opts, ms) {
+  try {
+    return await callAsync('showDialog', opts, ms);
+  } catch (e) {
+    return { cancel: true, reason: `dialog failed: ${e.message}` };
+  }
+}

package/src/platform/darwin/keys.js

@@ -0,0 +1,49 @@
+// "cmd+shift+t" style chords -> macOS virtual key codes (kVK_* from Carbon's HIToolbox/Events.h).
+//
+// The one subtle thing: `ctrl` is the literal Control key (kVK_Control, 59), NOT Command. Chords written for
+// Windows ("ctrl+c") therefore do not copy on a Mac; use "cmd" (also spelled win / meta / super) for that.
+// `alt` is Option. Codes are physical-key (ANSI layout) codes, as the OS expects for key events.
+export const KVK = {
+  a: 0, s: 1, d: 2, f: 3, h: 4, g: 5, z: 6, x: 7, c: 8, v: 9, b: 11, q: 12, w: 13, e: 14, r: 15, y: 16, t: 17,
+  o: 31, u: 32, i: 34, p: 35, l: 37, j: 38, k: 40, n: 45, m: 46,
+  1: 18, 2: 19, 3: 20, 4: 21, 6: 22, 5: 23, 9: 25, 7: 26, 8: 28, 0: 29,
+  '=': 24, '-': 27, ']': 30, '[': 33, "'": 39, ';': 41, '\\': 42, ',': 43, '/': 44, '.': 47, '`': 50,
+  return: 36, tab: 48, space: 49, delete: 51 /* backspace */, escape: 53, command: 55, shift: 56, capslock: 57,
+  option: 58, control: 59, rshift: 60, roption: 61, rcontrol: 62, rcommand: 54, fn: 63,
+  forwarddelete: 117, home: 115, end: 119, pageup: 116, pagedown: 121, help: 114,
+  left: 123, right: 124, down: 125, up: 126,
+  f1: 122, f2: 120, f3: 99, f4: 118, f5: 96, f6: 97, f7: 98, f8: 100, f9: 101, f10: 109, f11: 103, f12: 111,
+  f13: 105, f14: 107, f15: 113, f16: 106, f17: 64, f18: 79, f19: 80, f20: 90,
+};
+
+const NAMED = {
+  win: 55, windows: 55, meta: 55, cmd: 55, command: 55, super: 55, lwin: 55, rwin: 54,
+  ctrl: 59, control: 59, shift: 56, alt: 58, option: 58, opt: 58, menu: 58,
+  enter: 36, return: 36, esc: 53, escape: 53, tab: 48, space: 49,
+  backspace: 51, delete: 117, del: 117, insert: 114, ins: 114, // Mac "delete" is backspace; forward delete is the Windows Delete
+  home: 115, end: 119, pageup: 116, pgup: 116, pagedown: 121, pgdn: 121,
+  left: 123, up: 126, right: 124, down: 125,
+  ',': 43, '.': 47, '-': 27, '=': 24, '/': 44, ';': 41, "'": 39, '[': 33, ']': 30, '\\': 42, '`': 50,
+};
+
+const CMD = new Set([55, 54]);
+const V = 9;
+
+export function parseChord(chord) {
+  const parts = chord.trim().toLowerCase().split('+').map((s) => s.trim()).filter(Boolean);
+  if (!parts.length) throw new Error('Empty key chord.');
+  return parts.map((p) => {
+    if (NAMED[p] !== undefined) return NAMED[p];
+    if (/^f([1-9]|1\d|20)$/.test(p)) return KVK[p];
+    if (/^[a-z0-9]$/.test(p)) return KVK[p];
+    throw new Error(`Unknown key "${p}". Use names like cmd, ctrl, shift, alt, enter, tab, esc, f5, a-z, 0-9 (macOS has no f21-f24).`);
+  });
+}
+
+/** "cmd+a cmd+c" -> two chords. */
+export const parseSequence = (s) => s.trim().split(/\s+/).filter(Boolean).map(parseChord);
+
+/** Chords that paste (Cmd+V, Cmd+Shift+V, Cmd+Option+Shift+V): must not go into a password field. */
+export function insertsContent(codes) {
+  return codes.some((k) => CMD.has(k)) && codes.includes(V) && !codes.includes(59);
+}

package/src/platform/darwin/layer.js

@@ -0,0 +1,87 @@
+// Effect windows and text masks on macOS. The app owns the window; the pixels live in a file that both
+// processes map into memory, so no pixel data crosses the socket (PROTOCOL.md, "Layers").
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { callSync, post } from './rpc.js';
+
+const PROT_READ = 1, PROT_WRITE = 2, MAP_SHARED = 1, O_RDWR = 2;
+
+let libc = null;
+const require = createRequire(import.meta.url);
+/** koffi and libSystem load on first use (Layer's constructor is synchronous), so importing this works on every OS. */
+function libcSync() {
+  if (libc) return libc;
+  const koffi = require('koffi');
+  const lib = koffi.load('/usr/lib/libSystem.B.dylib');
+  libc = {
+    koffi,
+    open: lib.func('int open(const char *path, int flags)'),
+    close: lib.func('int close(int fd)'),
+    mmap: lib.func('void *mmap(void *addr, size_t len, int prot, int flags, int fd, int64_t off)'),
+    munmap: lib.func('int munmap(void *addr, size_t len)'),
+  };
+  return libc;
+}
+
+export class Layer {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+    this.shown = false;
+    this.id = 0;
+    this.map = null;
+    const len = width * height * 4;
+    const r = callSync('layerCreate', { width, height });
+    this.id = r.layer;
+    try {
+      const c = libcSync();
+      const fd = c.open(r.file, O_RDWR);
+      if (fd < 0) throw new Error(`cannot open ${r.file}`);
+      let ptr;
+      try {
+        ptr = c.mmap(null, len, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+      } finally {
+        c.close(fd); // the mapping stays valid after close
+      }
+      if (!ptr) throw new Error(`mmap of ${r.file} failed`);
+      this.map = ptr;
+      this.px = new Uint8Array(c.koffi.view(ptr, len));
+    } catch (e) {
+      post('layerDestroy', { layer: this.id });
+      throw new Error(`Could not map the effect window buffer: ${e.message}`);
+    }
+  }
+
+  /** Shows the top-left `width` x `height` part of the buffer, starting at row srcY, at (x, y) with opacity `alpha` (0-255). */
+  present(x, y, alpha, height = this.height, width = this.width, srcY = 0) {
+    post('layerPresent', {
+      layer: this.id,
+      x: Math.round(x),
+      y: Math.round(y),
+      alpha: Math.max(0, Math.min(255, Math.round(alpha))),
+      height: Math.max(1, Math.min(this.height, Math.round(height))),
+      width: Math.max(1, Math.min(this.width, Math.round(width))),
+      srcY: Math.max(0, Math.round(srcY)),
+    });
+    this.shown = true;
+  }
+
+  destroy() {
+    if (!this.id) return;
+    try { post('layerDestroy', { layer: this.id }); } catch { /* app gone */ }
+    this.id = 0;
+    if (this.map) {
+      try { libc.munmap(this.map, this.width * this.height * 4); } catch { /* already unmapped */ }
+      this.map = null;
+    }
+    this.px = new Uint8Array(0);
+  }
+}
+
+/** Anti-aliased text coverage (0-255 per pixel) in the system UI font, rendered by the app. */
+export function textMask(text, heightPx = 22, weight = 600) {
+  const r = callSync('textMask', { text, heightPx, weight });
+  const data = fs.readFileSync(r.file);
+  if (data.length < r.width * r.height) throw new Error(`textMask file is too short (${data.length} bytes for ${r.width}x${r.height}).`);
+  return { width: r.width, height: r.height, mask: new Uint8Array(data.buffer, data.byteOffset, r.width * r.height) };
+}

package/src/platform/darwin/overlay.js

@@ -0,0 +1,83 @@
+// The "working / stopped / cancelled" banner. Timers and texts are the same as the Windows overlay; the app
+// draws it (overlayShow / overlayHide). Calls are fire-and-forget so a banner can never stall a tool.
+import { post, callAsync } from './rpc.js';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const NAME = 'ispyx';
+
+export class Overlay {
+  constructor({ enabled = true, hideAfterMs = 1500, stopLabel = 'Option+Esc' } = {}) {
+    this.stopLabel = stopLabel;
+    this.enabled = enabled;
+    this.hideAfterMs = hideAfterMs;
+    this.active = 0;
+    this.stopped = false;
+    this.visible = false;
+    this.text = '';
+    this.timer = null;
+  }
+
+  _show(text) {
+    this.text = text;
+    this.visible = true;
+    post('overlayShow', { text, kind: this.stopped ? 'stopped' : 'running' });
+  }
+
+  _hide() {
+    this.visible = false;
+    post('overlayHide');
+  }
+
+  /** A tool started: show the banner. Call done() when it ends. */
+  begin(label) {
+    if (!this.enabled) return;
+    this.active++;
+    clearTimeout(this.timer);
+    this._show(`${NAME} is working: ${label}   |   To stop press ${this.stopLabel}`);
+  }
+
+  done() {
+    if (!this.enabled) return;
+    this.active = Math.max(0, this.active - 1);
+    if (this.active === 0) {
+      clearTimeout(this.timer);
+      this.timer = setTimeout(() => this._hide(), this.hideAfterMs);
+      this.timer.unref();
+    }
+  }
+
+  /** The user stopped the server: turn the banner red and keep it for a few seconds. */
+  stop(reason) {
+    if (!this.enabled) return;
+    this.stopped = true;
+    clearTimeout(this.timer);
+    this._show(`${NAME} STOPPED (${reason})`);
+    this.timer = setTimeout(() => this._hide(), 5000);
+    this.timer.unref();
+  }
+
+  /** First stop press: the running tool was cancelled; a second press within the window shuts the server down. */
+  cancel(reason, windowMs) {
+    if (!this.enabled) return;
+    this.active = 0;
+    clearTimeout(this.timer);
+    this._show(`${NAME} CANCELLED (${reason})   |   press again to shut down`);
+    this.timer = setTimeout(() => this._hide(), windowMs);
+    this.timer.unref();
+  }
+
+  /** Hide the banner while the agent takes a screenshot, so it never covers what the agent needs to see. */
+  async hiddenDuring(fn) {
+    const visible = this.enabled && this.visible;
+    if (visible) {
+      this._hide();
+      try { await callAsync('overlayVisible'); } catch { /* ordering is what matters */ }
+      await sleep(60); // let the compositor drop it
+    }
+    try {
+      return await fn();
+    } finally {
+      if (visible) this._show(this.text);
+    }
+  }
+}

package/src/platform/darwin/panel.js

@@ -0,0 +1,25 @@
+// The server side of the Ispyx window on macOS. The app shows the shared panel page (src/core/panel/page.html) and
+// owns what it knows itself (permissions, start at login, connect info); activity, effects, password and denylist
+// live in the server, so the app asks the owner for them:
+//   app -> client  event  { event: 'panelRequest', req, kind: 'state' | 'action', name, value }
+//   client -> app  call   panelReply({ req, ok, result } | { req, ok: false, error })
+// (`req`, not `id`: a line with an id is taken for the answer to a call, see rpc-worker.js)
+// Only the owner serves (it is the one process that runs the tools); the app takes the first reply.
+import { onEvent, post } from './rpc.js';
+
+/** model: { getState(), actions: { name(value) } } from core/resident.js panelModel. Returns an unsubscribe function. */
+export function servePanel(model) {
+  return onEvent('panelRequest', async (m) => {
+    const { req, kind, name, value } = m ?? {};
+    if (req === undefined) return;
+    try {
+      let result;
+      if (kind === 'state') result = model.getState();
+      else if (kind === 'action' && Object.hasOwn(model.actions, name)) result = await model.actions[name](value ?? undefined);
+      else throw new Error(`Unknown panel action ${name}`);
+      post('panelReply', { req, ok: true, result: result ?? null });
+    } catch (e) {
+      post('panelReply', { req, ok: false, error: e.message });
+    }
+  });
+}