Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

17.3 KB
Raw Blame
import {
  formatHotkeyLabelForPlatform,
  isGlobeLikeHotkey,
  isMouseButtonHotkey,
  parseHotkeyList,
} from "./hotkeys.ts";

export type Platform = "darwin" | "win32" | "linux";

export type ValidationErrorCode =
  | "TOO_MANY_KEYS"
  | "NO_MODIFIER_OR_SPECIAL"
  | "LEFT_RIGHT_MIX"
  | "LEFT_MODIFIER_ONLY"
  | "DUPLICATE"
  | "RESERVED"
  | "INVALID_GLOBE"
  | "FN_COMBINATION_UNSUPPORTED"
  | "MODIFIER_ONLY_UNSUPPORTED";

export interface ValidationResult {
  valid: boolean;
  error?: string;
  errorCode?: ValidationErrorCode;
}

const MODIFIER_ORDER = ["Control", "Command", "Alt", "Shift", "Super", "Fn"];

const MODIFIERS = new Set(MODIFIER_ORDER);

const RIGHT_SIDE_MODIFIERS = new Set([
  "rightcontrol",
  "rightctrl",
  "rightalt",
  "rightoption",
  "rightshift",
  "rightcommand",
  "rightcmd",
  "rightsuper",
  "rightmeta",
  "rightwin",
  "controlright",
  "ctrlright",
  "altright",
  "optionright",
  "shiftright",
  "commandright",
  "cmdright",
  "superright",
  "metaright",
  "winright",
]);

const LEFT_SIDE_MODIFIERS = new Set([
  "leftcontrol",
  "leftctrl",
  "leftalt",
  "leftoption",
  "leftshift",
  "leftcommand",
  "leftcmd",
  "leftsuper",
  "leftmeta",
  "leftwin",
  "controlleft",
  "ctrlleft",
  "altleft",
  "optionleft",
  "shiftleft",
  "commandleft",
  "cmdleft",
  "superleft",
  "metaleft",
  "winleft",
]);

function isRightSideModifier(part: string): boolean {
  const normalized = part.replace(/[-_ ]/g, "").toLowerCase();
  return RIGHT_SIDE_MODIFIERS.has(normalized);
}

function isLeftSideModifier(part: string): boolean {
  const normalized = part.replace(/[-_ ]/g, "").toLowerCase();
  return LEFT_SIDE_MODIFIERS.has(normalized);
}

const SPECIAL_KEYS = new Set(
  [
    "GLOBE",
    "Fn",
    "Esc",
    "Tab",
    "Space",
    "Backspace",
    "Insert",
    "Delete",
    "Home",
    "End",
    "PageUp",
    "PageDown",
    "Left",
    "Right",
    "Up",
    "Down",
    "PrintScreen",
    "Pause",
    "ScrollLock",
    "NumLock",
  ].concat(Array.from({ length: 24 }, (_, i) => `F${i + 1}`))
);

const MAC_RESERVED_SHORTCUTS = [
  "Command+C",
  "Command+V",
  "Command+X",
  "Command+Z",
  "Command+Shift+Z",
  "Command+A",
  "Command+Q",
  "Command+W",
  "Command+R",
  "Command+T",
  "Command+S",
  "Command+P",
  "Command+N",
  "Command+M",
  "Command+H",
  "Command+F",
  "Command+G",
  "Command+Shift+G",
  "Command+,",
  "Command+Left",
  "Command+Right",
  "Command+Up",
  "Command+Down",
  "Command+Shift+Left",
  "Command+Shift+Right",
  "Command+Shift+Up",
  "Command+Shift+Down",
  "Command+Control+F",
  "Command+Space",
  "Command+Alt+Space",
  "Command+Shift+3",
  "Command+Shift+4",
  "Command+Shift+5",
  "Command+Alt+Esc",
  "Command+Alt+D",
  "Command+Delete",
  "Command+Shift+Delete",
  "Command+Shift+Q",
  "Command+B",
  "Command+I",
  "Command+U",
  "Command+Shift+T",
  "Command+=",
  "Command+-",
  "Command+Alt+F",
  "Command+Shift+F",
  "Fn+F11",
  "Fn+F12",
] as const;

const WINDOWS_RESERVED_SHORTCUTS = [
  "Control+C",
  "Control+V",
  "Control+X",
  "Control+Z",
  "Control+Y",
  "Control+R",
  "Control+A",
  "Control+F",
  "Control+G",
  "Control+O",
  "Control+S",
  "Control+P",
  "Control+N",
  "Control+T",
  "Control+W",
  "Control+Home",
  "Control+End",
  "Control+Alt+Delete",
  "Control+Shift+Esc",
  "Control+Backspace",
  "Control+Delete",
  "Control+K",
  "Control+Shift+T",
  "Control+=",
  "Control+-",
  "Alt+Tab",
  "Alt+F4",
  "Alt+Left",
  "Alt+Right",
  "Alt+PrintScreen",
  "F5",
  "F11",
  "Home",
  "End",
  "PrintScreen",
  "Super+E",
  "Super+R",
  "Super+L",
  "Super+D",
  "Super+Tab",
  "Super+I",
  "Super+S",
  "Super+X",
  "Super+P",
  "Super+Q",
  "Super+U",
  "Super+B",
  "Super+Up",
  "Super+Down",
] as const;

const LINUX_RESERVED_SHORTCUTS = [
  "Control+C",
  "Control+V",
  "Control+X",
  "Control+Z",
  "Control+Y",
  "Control+R",
  "Control+A",
  "Control+F",
  "Control+G",
  "Control+O",
  "Control+S",
  "Control+P",
  "Control+N",
  "Control+T",
  "Control+W",
  "Control+Q",
  "Control+H",
  "Control+L",
  "Control+Home",
  "Control+End",
  "Control+Backspace",
  "Control+Delete",
  "Control+Shift+T",
  "Control+Shift+Q",
  "Control+=",
  "Control+-",
  "Control+Alt+T",
  "Control+Alt+Delete",
  "Control+Alt+L",
  "Control+Alt+Esc",
  "Control+Alt+Left",
  "Control+Alt+Right",
  "Control+Alt+Up",
  "Control+Alt+Down",
  "Control+Alt+D",
  "Control+Alt+S",
  "Control+Alt+Tab",
  "Alt+Tab",
  "Alt+Shift+Tab",
  "Alt+F1",
  "Alt+F2",
  "Alt+F4",
  "Alt+F7",
  "Alt+F8",
  "Alt+F9",
  "Alt+F10",
  "Alt+Space",
  "Alt+Left",
  "Alt+Right",
  "Alt+PrintScreen",
  "Super",
  "Super+A",
  "Super+D",
  "Super+L",
  "Super+S",
  "Super+M",
  "Super+Tab",
  "Super+Space",
  "Super+Left",
  "Super+Right",
  "Super+Up",
  "Super+Down",
  "Super+Shift+Left",
  "Super+Shift+Right",
  "Super+Shift+Up",
  "Super+Shift+Down",
  "Super+PageUp",
  "Super+PageDown",
  "Super+Home",
  "Super+End",
  "F1",
  "F5",
  "F11",
  "PrintScreen",
  "Shift+PrintScreen",
  "Super+PrintScreen",
] as const;

const MAC_EXAMPLES = [
  "Control+Shift+K",
  "Alt+F7",
  "Command+Shift+9",
  "Control+Space",
  "Control+Alt+M",
  "Shift+F9",
] as const;

const WINDOWS_EXAMPLES = [
  "Control+Shift+K",
  "Alt+F7",
  "Control+Space",
  "Control+Alt+M",
  "Shift+F9",
] as const;

const LINUX_EXAMPLES = [
  "Control+Super+K",
  "Control+Shift+K",
  "Super+Shift+R",
  "Control+Shift+Space",
  "Shift+F9",
  "Control+Super+M",
] as const;

export const VALIDATION_RULES = [
  "Uses three keys or fewer",
  "Includes at least one modifier or non-alphanumeric key",
  "Does not mix left and right versions of the same modifier",
  "Is not reserved by the system",
] as const;

function normalizeModifier(part: string, platform: Platform): string | null {
  const trimmed = part.replace(/\s+/g, "");
  const lowered = trimmed.toLowerCase();

  if (lowered === "commandorcontrol" || lowered === "cmdorctrl") {
    return platform === "darwin" ? "Command" : "Control";
  }

  if (lowered === "command" || lowered === "cmd") {
    return "Command";
  }

  if (lowered === "control" || lowered === "ctrl") {
    return "Control";
  }

  if (lowered === "alt" || lowered === "option") {
    return "Alt";
  }

  if (lowered === "shift") {
    return "Shift";
  }

  if (lowered === "super" || lowered === "win" || lowered === "meta") {
    return platform === "darwin" ? "Command" : "Super";
  }

  if (lowered === "fn") {
    return "Fn";
  }

  // Handle right-side modifiers (e.g., RightControl, RightOption)
  // These are valid modifiers but we preserve their "Right" prefix for single-modifier validation
  if (isRightSideModifier(part)) {
    // Return a normalized form but mark it as a modifier
    if (lowered.includes("control") || lowered.includes("ctrl")) return "RightControl";
    if (lowered.includes("alt") || lowered.includes("option"))
      return platform === "darwin" ? "RightOption" : "RightAlt";
    if (lowered.includes("shift")) return "RightShift";
    if (lowered.includes("command") || lowered.includes("cmd")) return "RightCommand";
    if (lowered.includes("super") || lowered.includes("meta") || lowered.includes("win")) {
      return platform === "darwin" ? "RightCommand" : "RightSuper";
    }
  }

  // Handle left-side modifiers (e.g., LeftControl, ControlLeft, LeftOption)
  if (isLeftSideModifier(part)) {
    if (lowered.includes("control") || lowered.includes("ctrl")) return "LeftControl";
    if (lowered.includes("alt") || lowered.includes("option"))
      return platform === "darwin" ? "LeftOption" : "LeftAlt";
    if (lowered.includes("shift")) return "LeftShift";
    if (lowered.includes("command") || lowered.includes("cmd")) return "LeftCommand";
    if (lowered.includes("super") || lowered.includes("meta") || lowered.includes("win")) {
      return platform === "darwin" ? "LeftCommand" : "LeftSuper";
    }
  }

  return null;
}

function normalizeKeyToken(part: string): string {
  const trimmed = part.replace(/\s+/g, "");
  const lowered = trimmed.toLowerCase();

  if (lowered === "arrowleft") return "Left";
  if (lowered === "arrowright") return "Right";
  if (lowered === "arrowup") return "Up";
  if (lowered === "arrowdown") return "Down";
  if (lowered === "escape" || lowered === "esc") return "Esc";
  if (lowered === "printscreen" || lowered === "print") return "PrintScreen";
  if (lowered === "pageup" || lowered === "pgup") return "PageUp";
  if (lowered === "pagedown" || lowered === "pgdown") return "PageDown";
  if (lowered === "scrolllock") return "ScrollLock";
  if (lowered === "numlock") return "NumLock";
  if (lowered === "delete" || lowered === "del") return "Delete";
  if (lowered === "insert" || lowered === "ins") return "Insert";
  if (lowered === "space") return "Space";
  if (lowered === "tab") return "Tab";
  if (lowered === "home") return "Home";
  if (lowered === "end") return "End";
  if (lowered === "backspace") return "Backspace";
  if (lowered === "globe") return "GLOBE";
  if (lowered === "fn") return "Fn";
  if (lowered === "mousebutton4") return "MouseButton4";
  if (lowered === "mousebutton5") return "MouseButton5";

  const functionMatch = lowered.match(/^f(\d{1,2})$/);
  if (functionMatch) {
    return `F${functionMatch[1]}`;
  }

  if (trimmed.length === 1) {
    return trimmed.toUpperCase();
  }

  return trimmed;
}

function isLeftRightMix(parts: string[]): boolean {
  const sidesByModifier = new Map<string, Set<string>>();

  const patterns = [
    {
      regex: /^(left|right)[-_ ]?(ctrl|control|alt|option|shift|command|cmd|super|meta|win)$/i,
      sideIndex: 1,
      modIndex: 2,
    },
    {
      regex: /^(ctrl|control|alt|option|shift|command|cmd|super|meta|win)[-_ ]?(left|right)$/i,
      sideIndex: 2,
      modIndex: 1,
    },
  ];

  for (const rawPart of parts) {
    const part = rawPart.replace(/\s+/g, "");
    for (const { regex, sideIndex, modIndex } of patterns) {
      const match = part.match(regex);
      if (match) {
        const side = match[sideIndex].toLowerCase().includes("left") ? "left" : "right";
        const rawModifier = match[modIndex].toLowerCase();
        const normalizedModifier =
          rawModifier === "ctrl"
            ? "control"
            : rawModifier === "cmd"
              ? "command"
              : rawModifier === "option"
                ? "alt"
                : rawModifier === "win" || rawModifier === "meta"
                  ? "super"
                  : rawModifier;
        const set = sidesByModifier.get(normalizedModifier) ?? new Set<string>();
        set.add(side);
        sidesByModifier.set(normalizedModifier, set);
      }
    }
  }

  for (const set of sidesByModifier.values()) {
    if (set.size > 1) {
      return true;
    }
  }

  return false;
}

export function normalizeHotkey(hotkey: string, platform: Platform): string {
  if (!hotkey) return "";

  const parts = hotkey
    .split("+")
    .map((part) => part.trim())
    .filter(Boolean);

  const modifiers: string[] = [];
  const keys: string[] = [];

  for (const part of parts) {
    const normalizedModifier = normalizeModifier(part, platform);
    if (normalizedModifier) {
      modifiers.push(normalizedModifier);
      continue;
    }

    keys.push(normalizeKeyToken(part));
  }

  modifiers.sort((a, b) => MODIFIER_ORDER.indexOf(a) - MODIFIER_ORDER.indexOf(b));

  return [...modifiers, ...keys].join("+");
}

export function getReservedShortcuts(platform: Platform): readonly string[] {
  switch (platform) {
    case "darwin":
      return MAC_RESERVED_SHORTCUTS;
    case "win32":
      return WINDOWS_RESERVED_SHORTCUTS;
    case "linux":
      return LINUX_RESERVED_SHORTCUTS;
    default:
      return [];
  }
}

export function getValidExamples(platform: Platform): readonly string[] {
  switch (platform) {
    case "darwin":
      return MAC_EXAMPLES;
    case "win32":
      return WINDOWS_EXAMPLES;
    case "linux":
      return LINUX_EXAMPLES;
    default:
      return [];
  }
}

export function getValidationMessage(
  hotkey: string,
  platform: Platform,
  existingHotkeys: string[] = []
): string | null {
  const result = validateHotkey(hotkey, platform, existingHotkeys);
  if (result.valid) return null;

  if (result.errorCode === "RESERVED") {
    const label = formatHotkeyLabelForPlatform(hotkey, platform);
    return `${label} is reserved by the system`;
  }

  return result.error || "That shortcut is not supported";
}

export function validateHotkey(
  hotkey: string,
  platform: Platform,
  existingHotkeys: string[] = []
): ValidationResult {
  if (!hotkey || hotkey.trim() === "") {
    return { valid: false, error: "Please enter a valid shortcut." };
  }

  // A slot may hold several hotkeys as a comma-separated list (#936) — validate
  // each entry independently and return the first failure. parseHotkeyList keeps
  // comma-key hotkeys like "Control+," intact, so a single such hotkey falls
  // through to the regular single-hotkey validation below.
  if (hotkey.includes(",")) {
    const items = parseHotkeyList(hotkey);
    if (items.length === 0) {
      return { valid: false, error: "Please enter a valid shortcut." };
    }
    if (items.length > 1) {
      for (const item of items) {
        const result = validateHotkey(item, platform, existingHotkeys);
        if (!result.valid) return result;
      }
      return { valid: true };
    }
    hotkey = items[0];
  }

  if (isGlobeLikeHotkey(hotkey)) {
    if (platform !== "darwin") {
      return {
        valid: false,
        error: "The Globe/Fn key is only available on macOS.",
        errorCode: "INVALID_GLOBE",
      };
    }
    return { valid: true };
  }

  // Electron cannot represent Fn inside an accelerator. Stripping it would
  // register the base key globally, so the native listener supports standalone
  // Globe/Fn only.
  if (/^fn\+/i.test(hotkey)) {
    return {
      valid: false,
      error: "The Globe/Fn key can only be used by itself.",
      errorCode: "FN_COMBINATION_UNSUPPORTED",
    };
  }

  if (isMouseButtonHotkey(hotkey)) {
    if (platform !== "darwin") {
      return {
        valid: false,
        error: "Mouse button hotkeys are currently supported on macOS only.",
      };
    }
    return { valid: true };
  }

  // Mouse buttons cannot be combined with keyboard modifiers — they're handled
  // by a separate native event tap, not Electron's globalShortcut.
  if (/mousebutton[45]/i.test(hotkey)) {
    return {
      valid: false,
      error: "Mouse button hotkeys cannot be combined with other keys.",
    };
  }

  const parts = hotkey
    .split("+")
    .map((part) => part.trim())
    .filter(Boolean);

  if (parts.length > 3) {
    return {
      valid: false,
      error: "Shortcuts are limited to three keys.",
      errorCode: "TOO_MANY_KEYS",
    };
  }

  if (isLeftRightMix(parts)) {
    return {
      valid: false,
      error: "Do not mix left and right versions of the same modifier in one shortcut.",
      errorCode: "LEFT_RIGHT_MIX",
    };
  }

  let hasModifier = false;
  let hasSpecialKey = false;

  for (const part of parts) {
    const normalizedModifier = normalizeModifier(part, platform);
    if (normalizedModifier) {
      hasModifier = true;
      continue;
    }

    const normalizedKey = normalizeKeyToken(part);
    if (SPECIAL_KEYS.has(normalizedKey)) {
      hasSpecialKey = true;
    }
  }

  if (!hasModifier && !hasSpecialKey) {
    return {
      valid: false,
      error:
        "Shortcuts must include a modifier or a non-alphanumeric key (like arrows, space, or function keys).",
      errorCode: "NO_MODIFIER_OR_SPECIAL",
    };
  }

  // Check for modifier-only hotkeys: require right-side for single modifier, or 2+ modifiers
  const modifierCount = parts.filter((part) => normalizeModifier(part, platform) !== null).length;
  const hasBaseKey = parts.length > modifierCount;

  // Windows and Linux route a modifier-only chord to a native low-level listener;
  // macOS has no equivalent — the Globe listener reports Fn, right-side modifiers
  // and mouse buttons, nothing else — and Electron cannot register an accelerator
  // without a key, so the chord would be accepted here and then fail to bind.
  if (!hasBaseKey && modifierCount >= 2 && platform === "darwin") {
    return {
      valid: false,
      error:
        "Two-modifier shortcuts are not supported on macOS. Use a right-side modifier on its own (e.g. RightOption), or add a regular key.",
      errorCode: "MODIFIER_ONLY_UNSUPPORTED",
    };
  }

  if (!hasBaseKey && modifierCount === 1) {
    const singleMod = parts[0];
    if (!isRightSideModifier(singleMod)) {
      return {
        valid: false,
        error:
          platform === "darwin"
            ? "Single modifier hotkeys must use the right-side key (e.g., RightOption). Or add a regular key (e.g., Control+Space)."
            : "Single modifier hotkeys must use the right-side key (e.g., RightOption). Or use two modifiers (e.g., Control+Alt).",
        errorCode: "LEFT_MODIFIER_ONLY",
      };
    }
  }

  const normalizedHotkey = normalizeHotkey(hotkey, platform);
  const normalizedExisting = existingHotkeys.map((existing) => normalizeHotkey(existing, platform));

  if (normalizedExisting.includes(normalizedHotkey)) {
    return {
      valid: false,
      error: "That shortcut is already in use.",
      errorCode: "DUPLICATE",
    };
  }

  const reserved = getReservedShortcuts(platform);
  const normalizedReserved = reserved.map((entry) => normalizeHotkey(entry, platform));

  if (normalizedReserved.includes(normalizedHotkey)) {
    return {
      valid: false,
      error: "That shortcut is reserved by your system.",
      errorCode: "RESERVED",
    };
  }

  return { valid: true };
}