claude-kvm-native 1.0.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "claude-kvm-native",
+  "version": "1.0.0",
+  "description": "MCP server (Native) — control remote desktops via VNC, SSH and on-device VLM (macOS)",
+  "license": "MIT",
+  "author": "Rıza Emre ARAS <r.emrearas@proton.me>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/remrearas/claude-kvm-native.git"
+  },
+  "keywords": [
+    "mcp",
+    "vnc",
+    "kvm",
+    "claude",
+    "remote-desktop",
+    "automation",
+    "ssh",
+    "vlm",
+    "apple-silicon",
+    "native"
+  ],
+  "main": "index.js",
+  "bin": {
+    "claude-kvm-native": "index.js"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "tools/",
+    "utils/",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "test:integration": "node test/integration.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "sharp": "^0.33.5",
+    "ssh2": "^1.17.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.52.0",
+    "@types/node": "^25.2.3",
+    "@types/ssh2": "^1.15.5"
+  }
+}

package/tools/control.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Flow control tool definitions.
+ * @returns {Array<{name: string, description: string, inputSchema: Record<string, import('zod').ZodType>}>}
+ */
+export function controlTools() {
+  return [
+    {
+      name: 'wait',
+      description: 'Wait before the next action. Use when waiting for a page load, animation, or response.\nDo NOT use wait between simple actions (click, type) — only when the remote system needs time to process (page navigation, app launch).',
+      inputSchema: {
+        ms: z.number().int().min(100).max(5000).describe('Duration in milliseconds (100–5000)'),
+      },
+    },
+    {
+      name: 'health_check',
+      description: [
+        'Check VNC connection status and server info.',
+        'Returns connection state, resolution, latency, reconnect count, and memory usage.',
+        'Use when you suspect the connection may be unstable or to diagnose issues.',
+      ].join('\n'),
+      inputSchema: null,
+    },
+    {
+      name: 'task_complete',
+      description: 'Mark the task as successfully completed. Provide a brief summary.',
+      inputSchema: {
+        summary: z.string().describe('What was accomplished'),
+      },
+    },
+    {
+      name: 'task_failed',
+      description: 'Mark the task as failed. Explain why.',
+      inputSchema: {
+        reason: z.string().describe('Why the task could not be completed'),
+      },
+    },
+  ];
+}

package/tools/index.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { screenTools } from './screen.js';
+import { mouseTools } from './mouse.js';
+import { keyboardTools } from './keyboard.js';
+import { controlTools } from './control.js';
+import { sshTools } from './ssh.js';
+import { vlmTools } from './vlm.js';
+
+/**
+ * Aggregate all KVM tool definitions.
+ * @param {import('../lib/types.js').ScaledDisplay} display
+ * @param {object} [options]
+ * @param {boolean} [options.sshEnabled] - Whether SSH is configured
+ * @param {boolean} [options.vlmEnabled] - Whether VLM tool is available
+ * @returns {Array<{name: string, description: string, inputSchema: object}>}
+ */
+export function getToolDefinitions(display, options = {}) {
+  const tools = [
+    ...screenTools(),
+    ...mouseTools(display),
+    ...keyboardTools(),
+    ...controlTools(),
+  ];
+
+  if (options.sshEnabled) {
+    tools.push(...sshTools());
+  }
+
+  if (options.vlmEnabled) {
+    tools.push(...vlmTools(display));
+  }
+
+  return tools;
+}

package/tools/keyboard.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Keyboard instrument definition.
+ *
+ * @returns {Array<{name: string, description: string, inputSchema: Record<string, import('zod').ZodType>}>}
+ */
+export function keyboardTools() {
+  return [
+    {
+      name: 'keyboard',
+      description: [
+        'Keyboard control.',
+        '',
+        'Actions:',
+        '- press: Press a single key. Param: key.',
+        '  Named keys: enter, escape, tab, backspace, delete, space,',
+        '  up, down, left, right, home, end, pageup, pagedown, f1–f12.',
+        '- combo: Key combination with "+" separator. Param: keys.',
+        '  Modifiers: ctrl, alt, shift, meta. Examples: ctrl+c, ctrl+l.',
+        '- type: Type text character by character. Param: text.',
+        '- paste: Paste text via clipboard. Param: text. Faster and more reliable for long text or special characters.',
+        '',
+        'Tips:',
+        '- Use pagedown/pageup for page scrolling — faster than mouse scroll.',
+        '- Use tab to move between form fields instead of clicking each one.',
+        '- Use meta+l to focus the address bar in browsers.',
+        '- Use meta+w to close windows/tabs, meta+a to select all.',
+        '- Chain keyboard actions without screenshots between them — verify with diff_check at the end.',
+        '- paste is preferred over type for longer text. Both support Unicode and special characters.',
+        '- On macOS, paste falls back to typing character-by-character (VNC clipboard limitation).',
+      ].join('\n'),
+      inputSchema: {
+        action: z.enum(['press', 'combo', 'type', 'paste']),
+        key: z.string().describe('Key name. For: press.').optional(),
+        keys: z.string().describe('Key combo (e.g. "ctrl+c"). For: combo.').optional(),
+        text: z.string().describe('Text to type. For: type, paste.').optional(),
+      },
+    },
+  ];
+}

package/tools/mouse.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Mouse instrument definition.
+ *
+ * @param {import('../lib/types.js').ScaledDisplay} display
+ * @returns {Array<{name: string, description: string, inputSchema: Record<string, import('zod').ZodType>}>}
+ */
+export function mouseTools(display) {
+  const { width, height } = display;
+
+  return [
+    {
+      name: 'mouse',
+      description: [
+        `Mouse control. Screen: ${width}x${height}px, origin (0,0) at top-left.`,
+        '',
+        'Actions:',
+        '- move: Move cursor to (x,y).',
+        '- hover: Move to (x,y) and wait briefly for tooltips/dropdowns to appear.',
+        '- nudge: Offset cursor by (dx,dy) relative to current position.',
+        '- click: Left-click at current cursor position.',
+        '- click_at: Move to (x,y) and left-click in one step. For large targets.',
+        '- right_click: Right-click at current position.',
+        '- double_click: Double-click at current position.',
+        '- drag: Hold and drag from current position to (x,y).',
+        '- scroll: Scroll at current position.',
+        '',
+        'Tips:',
+        '- Prefer click_at over move+click — it is faster (one call instead of two).',
+        '- For page scrolling, STRONGLY prefer keyboard pagedown/pageup — much faster and more predictable than mouse scroll.',
+        '- Mouse scroll is unreliable for precise amounts, especially on macOS. Use only for small adjustments in scrollable panels.',
+        '- No screenshot is needed after every mouse action. Use diff_check to verify changes.',
+      ].join('\n'),
+      inputSchema: {
+        action: z.enum(['move', 'hover', 'nudge', 'click', 'click_at', 'right_click', 'double_click', 'drag', 'scroll']),
+        x: z.number().int().min(0).max(width - 1).describe('X coordinate. For: move, click_at, drag.').optional(),
+        y: z.number().int().min(0).max(height - 1).describe('Y coordinate. For: move, click_at, drag.').optional(),
+        dx: z.number().int().min(-20).max(20).describe('Horizontal offset. For: nudge.').optional(),
+        dy: z.number().int().min(-20).max(20).describe('Vertical offset. For: nudge.').optional(),
+        direction: z.enum(['up', 'down', 'left', 'right']).describe('For: scroll.').optional(),
+        amount: z.number().int().min(1).max(10).describe('Scroll steps. For: scroll.').optional(),
+      },
+    },
+  ];
+}

package/tools/screen.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+/**
+ * Screen instrument definitions.
+ *
+ * @returns {Array<{name: string, description: string, inputSchema: null}>}
+ */
+export function screenTools() {
+  return [
+    {
+      name: 'screenshot',
+      description: [
+        'Capture the full screen. Use to observe current state before acting.',
+        'IMPORTANT: Do NOT take a screenshot after every action. Only use when you need to:',
+        '- See the initial state of the screen',
+        '- Verify a complex visual result (page loaded, UI changed significantly)',
+        '- Read text or identify UI elements for the next action',
+        'For simple verifications, prefer diff_check (text-only, ~5ms) or cursor_crop (small image).',
+        'If you need to read text from the screen, take a screenshot and examine the image carefully.',
+      ].join('\n'),
+      inputSchema: null,
+    },
+    {
+      name: 'cursor_crop',
+      description: [
+        'Capture a small crop around the current cursor position.',
+        'Returns cursor coordinates and a cropped image with a red crosshair marking the cursor.',
+        'Use to verify cursor placement on small targets (buttons, links, icons).',
+        'Much cheaper than a full screenshot — prefer this for position verification.',
+      ].join('\n'),
+      inputSchema: null,
+    },
+    {
+      name: 'diff_check',
+      description: [
+        'Lightweight screen change detection. Compares current frame against the baseline.',
+        'Returns changeDetected: true/false — no image. Fast (~5ms).',
+        'Triggers on any pixel change — maximum sensitivity.',
+        'Use after actions to verify if something changed without the cost of a full screenshot.',
+        'Updates the baseline after comparison.',
+        'Typical workflow: set_baseline → action → diff_check → if changed, screenshot only if needed.',
+      ].join('\n'),
+      inputSchema: null,
+    },
+    {
+      name: 'set_baseline',
+      description: [
+        'Save current screen as the diff baseline.',
+        'Call before an action so diff_check can measure what changed after it.',
+      ].join('\n'),
+      inputSchema: null,
+    },
+  ];
+}

package/tools/ssh.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { z } from 'zod';
+
+/**
+ * SSH tool definitions.
+ * @returns {Array<{name: string, description: string, inputSchema: Record<string, import('zod').ZodType>}>}
+ */
+export function sshTools() {
+  return [
+    {
+      name: 'ssh',
+      description: [
+        'Execute a command on the remote machine via SSH.',
+        'Returns stdout, stderr, and exit code. Use for any shell operation on the target system.',
+        '',
+        'Capabilities:',
+        '- File system operations: ls, cat, mkdir, cp, mv, rm',
+        '- Process management: ps, kill, top',
+        '- System info: uname, hostname, df, free',
+        '- Package management: apt, brew, etc.',
+        '- Network: curl, wget, ping, netstat',
+        '',
+        'macOS-specific (when VNC target is macOS):',
+        '- AppleScript: osascript -e \'tell application "Finder" to get name of every window\'',
+        '- UI validation: osascript to verify UI state after VNC actions',
+        '- App control: open -a "Safari", osascript to interact with apps',
+        '- System preferences: defaults read, defaults write',
+        '- Clipboard: pbcopy, pbpaste (direct system clipboard access)',
+        '- Screenshots with metadata: screencapture command',
+        '',
+        'Tips:',
+        '- On macOS, combine VNC visual actions with SSH osascript validation for reliable automation.',
+        '- Use pbpaste via SSH to read clipboard contents after a VNC copy action.',
+        '- Use osascript to get precise window positions, button states, and menu items.',
+        '- Requires SSH_HOST, SSH_USER, and SSH_PASSWORD or SSH_KEY environment variables.',
+        '',
+        'macOS permission dialogs:',
+        '- First-time osascript access to an app (System Events, Finder, etc.) triggers a macOS permission dialog.',
+        '- The SSH command will timeout while waiting for approval. Use VNC screenshot to check for the dialog, click "Allow", then retry the command.',
+      ].join('\n'),
+      inputSchema: {
+        command: z.string().describe('The shell command to execute on the remote machine'),
+        timeout: z.number().int().min(1000).max(120000).optional()
+          .describe('Command timeout in milliseconds (default: 30000, max: 120000)'),
+      },
+    },
+  ];
+}

package/tools/vlm.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { z } from 'zod';
+
+/**
+ * VLM (Vision Language Model) tool definitions.
+ * Only registered when CLAUDE_KVM_VLM_TOOL_PATH environment variable is set.
+ *
+ * @param {import('../lib/types.js').ScaledDisplay} display
+ * @returns {Array<{name: string, description: string, inputSchema: Record<string, import('zod').ZodType>}>}
+ */
+export function vlmTools(display) {
+  const { width, height } = display;
+
+  return [
+    {
+      name: 'vlm_query',
+      description: [
+        'Run an on-device Vision Language Model on a cropped region of the screen.',
+        `Coordinates are in screen space (${width}×${height}px). Specify a rectangular region with (x, y, width, height).`,
+        '',
+        'Use cases:',
+        '- Read text from a specific UI element (OCR)',
+        '- Describe what is visible in a region',
+        '- Identify icons, colors, or visual states in a small area',
+        '- Answer visual questions about a cropped portion of the screen',
+        '',
+        'Tips:',
+        '- Keep the crop region focused and small for faster/better results.',
+        '- The prompt should be a clear question or instruction about the cropped image.',
+        '- Runs locally on Apple Silicon — no network latency, but inference takes a few seconds.',
+        '- Use verbose=true for timing/debug info on stderr.',
+        '- macOS only.',
+      ].join('\n'),
+      inputSchema: {
+        x: z.number().int().min(0).max(width - 1).describe('Left edge X coordinate of the crop region'),
+        y: z.number().int().min(0).max(height - 1).describe('Top edge Y coordinate of the crop region'),
+        width: z.number().int().min(1).max(width).describe('Width of the crop region in pixels'),
+        height: z.number().int().min(1).max(height).describe('Height of the crop region in pixels'),
+        prompt: z.string().min(1).describe('Question or instruction for the VLM about the cropped image'),
+        max_tokens: z.number().int().min(1).max(4096).optional().describe('Maximum tokens in VLM response (default: 1024)'),
+        verbose: z.boolean().optional().describe('Enable verbose logging to stderr for timing and debug info'),
+      },
+    },
+  ];
+}

package/utils/keysym.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+/**
+ * Character / Key Name → X11 Keysym mapping.
+ *
+ * VNC uses X11 keysyms for keyboard input.
+ * ASCII printable chars (0x20-0x7E) map directly to their code point.
+ * Special keys use the 0xFF** range.
+ *
+ * Reference: https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding
+ */
+
+// Special key keysyms
+const SPECIAL_KEYSYMS = {
+  backspace:    0xFF08,
+  tab:          0xFF09,
+  return:       0xFF0D,
+  enter:        0xFF0D,
+  ret:          0xFF0D,
+  escape:       0xFF1B,
+  esc:          0xFF1B,
+  delete:       0xFFFF,
+  del:          0xFFFF,
+
+  // Cursor control
+  home:         0xFF50,
+  left:         0xFF51,
+  up:           0xFF52,
+  right:        0xFF53,
+  down:         0xFF54,
+  pageup:       0xFF55,
+  pgup:         0xFF55,
+  pagedown:     0xFF56,
+  pgdn:         0xFF56,
+  end:          0xFF57,
+  insert:       0xFF63,
+
+  // Function keys
+  f1:           0xFFBE,
+  f2:           0xFFBF,
+  f3:           0xFFC0,
+  f4:           0xFFC1,
+  f5:           0xFFC2,
+  f6:           0xFFC3,
+  f7:           0xFFC4,
+  f8:           0xFFC5,
+  f9:           0xFFC6,
+  f10:          0xFFC7,
+  f11:          0xFFC8,
+  f12:          0xFFC9,
+
+  // Modifiers
+  shift:        0xFFE1,
+  shift_l:      0xFFE1,
+  shift_r:      0xFFE2,
+  ctrl:         0xFFE3,
+  ctrl_l:       0xFFE3,
+  ctrl_r:       0xFFE4,
+  control:      0xFFE3,
+  alt:          0xFFE9,
+  alt_l:        0xFFE9,
+  alt_r:        0xFFEA,
+  option:       0xFFE9,
+  opt:          0xFFE9,
+  meta:         0xFFE7,
+  meta_l:       0xFFE7,
+  meta_r:       0xFFE8,
+  cmd:          0xFFE7,
+  command:      0xFFE7,
+  super:        0xFFE7,
+  super_l:      0xFFE7,
+  super_r:      0xFFE8,
+
+  // Misc
+  space:        0x0020,
+  spc:          0x0020,
+  capslock:     0xFFE5,
+  numlock:      0xFF7F,
+  scrolllock:   0xFF14,
+  printscreen:  0xFF61,
+  print:        0xFF61,
+  pause:        0xFF13,
+  menu:         0xFF67,
+};
+
+// Characters that require Shift on a US keyboard layout
+const SHIFT_CHARS = new Set('~!@#$%^&*()_+{}|:"<>?ABCDEFGHIJKLMNOPQRSTUVWXYZ');
+
+/**
+ * Convert a printable character to its X11 keysym.
+ * For ASCII chars, the keysym equals the Unicode code point.
+ * @param {string} ch - Single character
+ * @returns {import('../lib/types').KeysymMapping | null}
+ */
+export function charToKeysym(ch) {
+  const code = ch.charCodeAt(0);
+
+  // Standard ASCII printable range (space through ~)
+  if (code >= 0x20 && code <= 0x7E) {
+    const shift = SHIFT_CHARS.has(ch);
+
+    // For uppercase letters, the keysym is the lowercase version
+    // but we send it with shift held down
+    if (ch >= 'A' && ch <= 'Z') {
+      return { keysym: ch.toLowerCase().charCodeAt(0), shift: true };
+    }
+
+    // For shifted symbols, the keysym is the character itself
+    // VNC expects the keysym of the actual character, with shift modifier
+    if (shift) {
+      return { keysym: code, shift: true };
+    }
+
+    return { keysym: code, shift: false };
+  }
+
+  // Latin-1 supplement (0x80-0xFF) — keysym equals code point
+  if (code >= 0xA0 && code <= 0xFF) {
+    return { keysym: code, shift: false };
+  }
+
+  // Unicode beyond Latin-1 (Turkish ığşİĞŞ, etc.)
+  // X11 keysym for Unicode: 0x01000000 + code point
+  if (code > 0xFF) {
+    const lower = ch.toLowerCase();
+    if (lower !== ch) {
+      // Uppercase Unicode — send lowercase keysym + shift (e.g. Ş → shift + ş)
+      return { keysym: 0x01000000 + lower.charCodeAt(0), shift: true };
+    }
+    return { keysym: 0x01000000 + code, shift: false };
+  }
+
+  return null;
+}
+
+/**
+ * Resolve a named key to its X11 keysym.
+ * @param {string} name - Key name (e.g. "enter", "cmd", "f5")
+ * @returns {number | null}
+ */
+export function namedKeyToKeysym(name) {
+  return SPECIAL_KEYSYMS[name.toLowerCase()] ?? null;
+}
+
+export { SPECIAL_KEYSYMS };