Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

31.8 KB
Raw Blame
/**
 * 应用级快捷键 registry —— 全部应用级快捷键的单一事实来源。
 *
 * 与 applicationMenuCommands.ts 并列且职责分离: commands 描述「菜单点击派发
 * 什么指令」, 本文件描述「什么按键组合触发什么动作」。两者在消费端 (菜单
 * click / renderer handler) 衔接, 互不合并。
 *
 * 纯常量 + 纯函数, 零 Electron / DOM 依赖 (platform 一律作参数传入),
 * main / preload / renderer 三端可 import。内部规范表示以 KeyboardEvent.code
 * 为基准 (物理键位, 布局无关, 与 voice-input 快捷键体系一致); Electron
 * accelerator 字符串与 before-input-event Input 均通过本文件的转换/匹配函数
 * 与该表示互通, 保证双端判定不漂移。
 *
 * 用户 override 只存差异 (见 main/app-shortcuts/AppShortcutStore), 默认值由
 * 本 registry 随版本演进; getEffectiveAppShortcuts 负责合并。
 */

/** 规范化组合键: code 为 W3C KeyboardEvent.code, key 仅供显示兜底不参与匹配。 */
export interface AppShortcutCombo {
  code: string;
  key?: string;
  meta: boolean;
  ctrl: boolean;
  alt: boolean;
  shift: boolean;
}

/**
 * 冲突检测域: app 与一切重叠; workdir-doc 与 browser / composer 也重叠, 因为
 * 文件预览可同屏挂载右侧浏览器和 chat rail, 且在 window capture 阶段消费快捷键。
 * global = 系统级全局快捷键 (main 用 globalShortcut 注册, Cindy 不在前台也生效),
 * Cindy 在前台时同样先于应用内监听截走按键, 因此与一切重叠。
 * 仅用于改绑冲突判定, 不做展示分组。
 */
export type AppShortcutScope = 'app' | 'workdir-doc' | 'browser' | 'composer' | 'global';

export const APP_SHORTCUT_IDS = [
  'toggle-sidebar',
  'session-history-back',
  'session-history-forward',
  'open-settings',
  'new-maker',
  'close-tab-or-window',
  'right-tab-prev',
  'right-tab-next',
  'find-in-page',
  'search-in-project',
  'save-file',
  'open-terminal',
  'zoom-in',
  'zoom-out',
  'zoom-reset',
  'browser-focus-url',
  'browser-back',
  'browser-forward',
  'browser-reload',
  'cycle-permission-mode',
  'region-screenshot',
  'switch-session-1',
  'switch-session-2',
  'switch-session-3',
  'switch-session-4',
  'switch-session-5',
  'switch-session-6',
  'switch-session-7',
  'switch-session-8',
  'switch-session-9',
] as const;

export type AppShortcutId = (typeof APP_SHORTCUT_IDS)[number];

/**
 * 侧边栏对话切换槽位: mod+1..9 跳转到侧边栏第 N 个可见对话(含置顶区, 按渲染
 * 顺序, 与 getVisibleSidebarSessionIds 同一口径)。逐 id 注册以完整复用改绑 /
 * 冲突检测 / accelerator 转换体系; 消费端与按住修饰键浮现的序号徽标见
 * renderer CCAgentSidebarUpper。数组序 = 槽位序 (index 0 ↔ 数字键 1)。
 */
export const SWITCH_SESSION_SHORTCUT_IDS = [
  'switch-session-1',
  'switch-session-2',
  'switch-session-3',
  'switch-session-4',
  'switch-session-5',
  'switch-session-6',
  'switch-session-7',
  'switch-session-8',
  'switch-session-9',
] as const satisfies readonly AppShortcutId[];

export interface AppShortcutDefinition {
  id: AppShortcutId;
  scope: AppShortcutScope;
  /** i18n key: settings.shortcuts.items.<id>.label */
  labelKey: string;
  /** i18n key: settings.shortcuts.items.<id>.description (设置页条目说明) */
  descriptionKey: string;
  rebindable: boolean;
  /** true = 不在设置页快捷键列表展示 (仍正常生效, 如 ⌘, 打开设置)。 */
  hiddenInSettings?: boolean;
  /**
   * true = 本条目的默认组合对用户既有绑定让位: 与其它 id 的 override 或
   * registry 之外体系的用户键位 (yieldToCombos) 撞键时, 默认组合被压制
   * (该槽位等效无绑定), 写入侧 findAppShortcutConflict 也不把它算作占用。
   * 只用于「批量占键的次要便捷槽位」(switch-session-*): 它们隐藏在设置页
   * 之外, 用户看不到也解不开, 不让位就会一次按键双动作。save-file / ⌘, 等
   * 惯例键虽也 hiddenInSettings 但**不得**设本字段 —— 否则用户把别的键改绑
   * 到 ⌘S 会被放行并静默丢失保存快捷键。
   */
  yieldsToUserBindings?: boolean;
  /**
   * true = darwin 上唯一触发路径是应用菜单 accelerator (无 renderer /
   * before-input-event fallback)。改绑时必须能转换为 Electron accelerator
   * (comboToElectronAccelerator 非 null), 否则 UI 显示已绑定但按键永不生效
   * —— store 与设置页双端都按此校验拦截。
   */
  menuBacked?: boolean;
  /** 缺省 = 全平台可用。 */
  platforms?: ReadonlyArray<'darwin' | 'win32' | 'linux'>;
  /**
   * 平台默认组合, 支持多默认 (如 reload = mod+R 与 F5)。用户 override 时以
   * 单个 combo 整体替换整个默认列表。
   */
  getDefaultCombos(platform: string): AppShortcutCombo[];
}

type ComboModifiers = Partial<Pick<AppShortcutCombo, 'meta' | 'ctrl' | 'alt' | 'shift'>>;

function combo(code: string, modifiers: ComboModifiers = {}): AppShortcutCombo {
  return {
    code,
    meta: Boolean(modifiers.meta),
    ctrl: Boolean(modifiers.ctrl),
    alt: Boolean(modifiers.alt),
    shift: Boolean(modifiers.shift),
  };
}

/** darwin 上 mod = ⌘, 其它平台 mod = Ctrl。 */
function modCombo(code: string, platform: string, extra: ComboModifiers = {}): AppShortcutCombo {
  return platform === 'darwin'
    ? combo(code, { ...extra, meta: true })
    : combo(code, { ...extra, ctrl: true });
}

// 数组顺序即设置页展示顺序: 高频动作在前 (新对话 → 侧边栏 → 权限模式 →
// 命令行 → 查找 → 缩放 → 浏览器)。hiddenInSettings 项不展示但仍正常生效。
export const APP_SHORTCUT_DEFINITIONS: ReadonlyArray<AppShortcutDefinition> = [
  {
    id: 'new-maker',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.new-maker.label',
    descriptionKey: 'settings.shortcuts.items.new-maker.description',
    rebindable: true,
    menuBacked: true,
    getDefaultCombos: (platform) => [modCombo('KeyN', platform)],
  },
  {
    id: 'toggle-sidebar',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.toggle-sidebar.label',
    descriptionKey: 'settings.shortcuts.items.toggle-sidebar.description',
    rebindable: true,
    getDefaultCombos: (platform) => [modCombo('KeyB', platform)],
  },
  // 任务浏览栈的前进/后退: 与浏览器同一惯例 (⌘[ / ⌘]), 在 ChromeActions
  // 的左上按钮簇里消费。raw 按键在 macOS 上不会被系统菜单吃掉
  // (keyboardReserved 不含 Bracket*), webview 内的 ⌘[ 留给浏览器自己的后退。
  {
    id: 'session-history-back',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.session-history-back.label',
    descriptionKey: 'settings.shortcuts.items.session-history-back.description',
    rebindable: true,
    // 新增默认键位对用户既有改绑让位:老用户把 toggle-sidebar 等动作改绑到 ⌘[ 是
    // 历史合法绑定,若两个动作同名生效,一次按键会同时切侧栏与后退。
    yieldsToUserBindings: true,
    getDefaultCombos: (platform) => [modCombo('BracketLeft', platform)],
  },
  {
    id: 'session-history-forward',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.session-history-forward.label',
    descriptionKey: 'settings.shortcuts.items.session-history-forward.description',
    rebindable: true,
    yieldsToUserBindings: true,
    getDefaultCombos: (platform) => [modCombo('BracketRight', platform)],
  },
  // 全局框选截图: Cindy 不在前台也生效,可复制、保存、贴图或交给新任务。默认键避开系统截图
  // (macOS ⇧⌘3/4/5/6、Windows Win+Shift+S) 与常见 IM 截图键 (Windows: Ctrl+Alt+A、
  // Alt+A、Ctrl+Shift+A; macOS: 飞书 ⇧⌘A、微信 / QQ ⌃⌘A)。macOS 不用 ⇧⌘S: 它是几乎所有
  // 应用的「存储为」, 全局注册会把它从每个应用里拿走。暂不支持 Linux (Wayland 无可靠的
  // 全局快捷键与静默截屏)。
  {
    id: 'region-screenshot',
    scope: 'global',
    labelKey: 'settings.shortcuts.items.region-screenshot.label',
    descriptionKey: 'settings.shortcuts.items.region-screenshot.description',
    rebindable: true,
    platforms: ['darwin', 'win32'],
    getDefaultCombos: (platform) =>
      platform === 'darwin'
        ? [combo('KeyA', { ctrl: true, shift: true })]
        : [combo('KeyA', { alt: true, shift: true })],
  },
  {
    id: 'cycle-permission-mode',
    scope: 'composer',
    labelKey: 'settings.shortcuts.items.cycle-permission-mode.label',
    descriptionKey: 'settings.shortcuts.items.cycle-permission-mode.description',
    rebindable: true,
    getDefaultCombos: () => [combo('Tab', { shift: true })],
  },
  // ⌘W / Ctrl+W 是系统级惯例键 (keyboardReserved 保留组合), 不开放改绑与设置页
  // 展示。行为按焦点分派: 焦点在右侧栏内 → 关激活 tab; 否则 mac 关(隐藏)当前
  // 窗口 (对齐原生菜单 role close), win/linux 不消费 (关窗惯例是 Alt+F4, 且主窗
  // 关闭 = 退出 app, 不能挂在 Ctrl+W 上)。菜单 Window > Close 改为
  // registerAccelerator: false 后按键流到 renderer, 由 MainLayout /
  // SidebarWindowLayout 消费; webview guest 内按键由 main 端 webview-security
  // 的 before-input-event 拦截转发。
  {
    id: 'close-tab-or-window',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.close-tab-or-window.label',
    descriptionKey: 'settings.shortcuts.items.close-tab-or-window.description',
    rebindable: false,
    hiddenInSettings: true,
    getDefaultCombos: (platform) => [modCombo('KeyW', platform)],
  },
  {
    id: 'right-tab-prev',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.right-tab-prev.label',
    descriptionKey: 'settings.shortcuts.items.right-tab-prev.description',
    rebindable: true,
    getDefaultCombos: (platform) =>
      platform === 'darwin'
        ? [combo('BracketLeft', { meta: true, shift: true }), combo('Tab', { ctrl: true, shift: true })]
        : [combo('PageUp', { ctrl: true }), combo('Tab', { ctrl: true, shift: true })],
  },
  {
    id: 'right-tab-next',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.right-tab-next.label',
    descriptionKey: 'settings.shortcuts.items.right-tab-next.description',
    rebindable: true,
    getDefaultCombos: (platform) =>
      platform === 'darwin'
        ? [combo('BracketRight', { meta: true, shift: true }), combo('Tab', { ctrl: true })]
        : [combo('PageDown', { ctrl: true }), combo('Tab', { ctrl: true })],
  },
  {
    id: 'open-terminal',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.open-terminal.label',
    descriptionKey: 'settings.shortcuts.items.open-terminal.description',
    rebindable: true,
    getDefaultCombos: () => [combo('Backquote', { ctrl: true })],
  },
  // ⌘, 打开设置是 macOS 系统惯例, 不在设置页暴露改绑入口 (仍正常生效)。
  {
    id: 'open-settings',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.open-settings.label',
    descriptionKey: 'settings.shortcuts.items.open-settings.description',
    rebindable: true,
    hiddenInSettings: true,
    menuBacked: true,
    platforms: ['darwin'],
    getDefaultCombos: () => [combo('Comma', { meta: true })],
  },
  {
    id: 'find-in-page',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.find-in-page.label',
    descriptionKey: 'settings.shortcuts.items.find-in-page.description',
    rebindable: true,
    getDefaultCombos: (platform) => [modCombo('KeyF', platform)],
  },
  {
    id: 'search-in-project',
    scope: 'workdir-doc',
    labelKey: 'settings.shortcuts.items.search-in-project.label',
    descriptionKey: 'settings.shortcuts.items.search-in-project.description',
    rebindable: true,
    getDefaultCombos: (platform) => [modCombo('KeyF', platform, { shift: true })],
  },
  // 保存是文档编辑的通用惯例键 (⌘S), 不在设置页暴露改绑入口 (仍正常生效)。
  {
    id: 'save-file',
    scope: 'workdir-doc',
    labelKey: 'settings.shortcuts.items.save-file.label',
    descriptionKey: 'settings.shortcuts.items.save-file.description',
    rebindable: true,
    hiddenInSettings: true,
    getDefaultCombos: (platform) => [modCombo('KeyS', platform)],
  },
  // 缩放三键: macOS 由系统菜单 role (resetZoom/zoomIn/zoomOut) 承担, 仅
  // win/linux 走 renderer 监听。多默认覆盖主键区与数字键盘 (与迁移前
  // MainLayout 按 e.key 匹配的行为对齐)。
  {
    id: 'zoom-in',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.zoom-in.label',
    descriptionKey: 'settings.shortcuts.items.zoom-in.description',
    rebindable: true,
    platforms: ['win32', 'linux'],
    getDefaultCombos: () => [
      combo('Equal', { ctrl: true }),
      combo('Equal', { ctrl: true, shift: true }),
      combo('NumpadAdd', { ctrl: true }),
    ],
  },
  {
    id: 'zoom-out',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.zoom-out.label',
    descriptionKey: 'settings.shortcuts.items.zoom-out.description',
    rebindable: true,
    platforms: ['win32', 'linux'],
    getDefaultCombos: () => [
      combo('Minus', { ctrl: true }),
      combo('NumpadSubtract', { ctrl: true }),
    ],
  },
  {
    id: 'zoom-reset',
    scope: 'app',
    labelKey: 'settings.shortcuts.items.zoom-reset.label',
    descriptionKey: 'settings.shortcuts.items.zoom-reset.description',
    rebindable: true,
    platforms: ['win32', 'linux'],
    getDefaultCombos: () => [
      combo('Digit0', { ctrl: true }),
      combo('Numpad0', { ctrl: true }),
    ],
  },
  {
    id: 'browser-focus-url',
    scope: 'browser',
    labelKey: 'settings.shortcuts.items.browser-focus-url.label',
    descriptionKey: 'settings.shortcuts.items.browser-focus-url.description',
    rebindable: true,
    getDefaultCombos: (platform) => [modCombo('KeyL', platform)],
  },
  {
    id: 'browser-back',
    scope: 'browser',
    labelKey: 'settings.shortcuts.items.browser-back.label',
    descriptionKey: 'settings.shortcuts.items.browser-back.description',
    rebindable: true,
    getDefaultCombos: () => [combo('ArrowLeft', { alt: true })],
  },
  {
    id: 'browser-forward',
    scope: 'browser',
    labelKey: 'settings.shortcuts.items.browser-forward.label',
    descriptionKey: 'settings.shortcuts.items.browser-forward.description',
    rebindable: true,
    getDefaultCombos: () => [combo('ArrowRight', { alt: true })],
  },
  {
    id: 'browser-reload',
    scope: 'browser',
    labelKey: 'settings.shortcuts.items.browser-reload.label',
    descriptionKey: 'settings.shortcuts.items.browser-reload.description',
    rebindable: true,
    getDefaultCombos: (platform) => [modCombo('KeyR', platform), combo('F5')],
  },
  // 对话切换 9 槽位 (见 SWITCH_SESSION_SHORTCUT_IDS 注释)。设置页不逐条展示
  // (9 行同构条目刷屏), 但 label/description i18n 仍需齐全 —— 改绑冲突提示
  // 会引用占用者 label。
  ...SWITCH_SESSION_SHORTCUT_IDS.map(
    (id, index): AppShortcutDefinition => ({
      id,
      scope: 'app',
      labelKey: `settings.shortcuts.items.${id}.label`,
      descriptionKey: `settings.shortcuts.items.${id}.description`,
      rebindable: true,
      hiddenInSettings: true,
      yieldsToUserBindings: true,
      getDefaultCombos: (platform) => [modCombo(`Digit${index + 1}`, platform)],
    }),
  ),
];

const DEFINITION_MAP: ReadonlyMap<AppShortcutId, AppShortcutDefinition> = new Map(
  APP_SHORTCUT_DEFINITIONS.map((def) => [def.id, def]),
);

export function isAppShortcutId(value: unknown): value is AppShortcutId {
  return typeof value === 'string' && DEFINITION_MAP.has(value as AppShortcutId);
}

export function getAppShortcutDefinition(id: AppShortcutId): AppShortcutDefinition {
  const def = DEFINITION_MAP.get(id);
  if (!def) throw new Error(`unknown app shortcut id: ${id}`);
  return def;
}

export function isAppShortcutAvailableOnPlatform(id: AppShortcutId, platform: string): boolean {
  const def = DEFINITION_MAP.get(id);
  if (!def) return false;
  if (!def.platforms) return true;
  return (def.platforms as readonly string[]).includes(platform);
}

/** 用户 override 集合: 只含用户显式改过的 id。 */
/**
 * 用户 override 值: combo = 改绑到新组合; null = 删除绑定 (该快捷键禁用,
 * 生效组合为空列表, 所有消费端自然不匹配)。
 */
export type AppShortcutOverrideValue = AppShortcutCombo | null;
export type AppShortcutOverrides = Partial<Record<AppShortcutId, AppShortcutOverrideValue>>;

/** 校验并规整单个 combo; 结构非法返回 null。 */
export function normalizeAppShortcutCombo(raw: unknown): AppShortcutCombo | null {
  if (!raw || typeof raw !== 'object') return null;
  const candidate = raw as Partial<AppShortcutCombo>;
  if (typeof candidate.code !== 'string' || candidate.code.trim().length === 0) return null;
  if (MODIFIER_CODES.has(candidate.code)) return null;
  return {
    code: candidate.code,
    key: typeof candidate.key === 'string' ? candidate.key : undefined,
    meta: Boolean(candidate.meta),
    ctrl: Boolean(candidate.ctrl),
    alt: Boolean(candidate.alt),
    shift: Boolean(candidate.shift),
  };
}

/**
 * 非可改绑快捷键的默认组合是"代码保留键" (如 close-tab-or-window 的 mod+W)。
 * 历史版本存下的 override 可能与之撞键 —— 该保留键引入前, 用户把 toggle-sidebar /
 * open-terminal / browser-* 等改绑到同一组合是合法写入, 而冲突只在新写入时校验,
 * load 不重查。撞键的存量 override 必须在归一化时丢弃 (该 id 自愈回默认值),
 * 否则消费端各自独立的监听 (renderer useAppShortcut / guest before-input-event)
 * 会让旧动作与保留键动作并发触发。
 */
function collidesWithNonRebindableDefault(
  comboValue: AppShortcutCombo,
  platform: string,
): boolean {
  for (const def of APP_SHORTCUT_DEFINITIONS) {
    if (def.rebindable) continue;
    if (!isAppShortcutAvailableOnPlatform(def.id, platform)) continue;
    if (def.getDefaultCombos(platform).some((c) => appShortcutCombosEqual(c, comboValue))) {
      return true;
    }
  }
  return false;
}

/**
 * 规整 override 集合: 丢弃未知 id、不可改绑 id、当前平台不可用 id、非法
 * combo、与不可改绑快捷键默认组合撞键的存量 combo。null 值 (删除绑定) 原样
 * 保留。版本升级删除某 id 后, 存量 override 在 load 时自动自愈。
 */
export function normalizeAppShortcutOverrides(raw: unknown, platform: string): AppShortcutOverrides {
  if (!raw || typeof raw !== 'object') return {};
  const result: AppShortcutOverrides = {};
  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
    if (!isAppShortcutId(key)) continue;
    const def = DEFINITION_MAP.get(key);
    if (!def || !def.rebindable) continue;
    if (!isAppShortcutAvailableOnPlatform(key, platform)) continue;
    if (value === null) {
      result[key] = null;
      continue;
    }
    const normalized = normalizeAppShortcutCombo(value);
    if (!normalized) continue;
    if (collidesWithNonRebindableDefault(normalized, platform)) continue;
    result[key] = normalized;
  }
  return result;
}

/**
 * 默认值 + override 合并出每个 id 的生效组合列表。override 为单 combo 时
 * 整体替换默认列表; null (删除绑定) → 空列表; 平台不可用的 id 不出现在
 * 结果里 (消费端对 undefined / 空列表自动不挂监听)。
 *
 * yieldsToUserBindings 条目的默认组合对用户既有绑定让位: 冲突只在写入时
 * 校验, 历史版本合法写下的绑定可能与后续版本新增的批量默认撞键 (如
 * switch-session-* 一次性占入 mod+1..9)。这些槽位不在设置页出现, 用户
 * 看不到占用者也无法解绑, 若不让位则一次按键触发两个动作。让位后该槽位
 * 等效无绑定 (消费端与序号徽标端对空组合天然兼容); 其余条目 —— 包括
 * save-file / open-settings 等同样 hiddenInSettings 的惯例键 —— 不让位,
 * 维持既有行为 (见 yieldsToUserBindings 字段注释)。让位对象有两类:
 * 1. 本 registry 内其它 id 的用户 override (overrides 参数);
 * 2. registry 之外体系的用户键位 (yieldToCombos 参数, 如语音输入的键盘
 *    快捷键) —— 由知道该体系的消费端传入; 无此类消费的调用点 (如 main 的
 *    菜单 accelerator, 这些隐藏槽位本就不进菜单) 不传即可, 行为不变。
 */
export function getEffectiveAppShortcuts(
  overrides: AppShortcutOverrides,
  platform: string,
  yieldToCombos: ReadonlyArray<AppShortcutCombo> = [],
): Map<AppShortcutId, AppShortcutCombo[]> {
  const overrideEntries: Array<{ scope: AppShortcutScope; combo: AppShortcutCombo }> = [];
  for (const def of APP_SHORTCUT_DEFINITIONS) {
    if (!isAppShortcutAvailableOnPlatform(def.id, platform)) continue;
    const override = overrides[def.id];
    if (override) overrideEntries.push({ scope: def.scope, combo: override });
  }
  const result = new Map<AppShortcutId, AppShortcutCombo[]>();
  for (const def of APP_SHORTCUT_DEFINITIONS) {
    if (!isAppShortcutAvailableOnPlatform(def.id, platform)) continue;
    const override = overrides[def.id];
    if (override === null) {
      result.set(def.id, []);
      continue;
    }
    if (override) {
      result.set(def.id, [override]);
      continue;
    }
    let combos = def.getDefaultCombos(platform);
    if (def.yieldsToUserBindings) {
      combos = combos.filter(
        (c) =>
          !overrideEntries.some(
            (o) => appShortcutScopesOverlap(def.scope, o.scope) && appShortcutCombosEqual(o.combo, c),
          ) && !yieldToCombos.some((y) => appShortcutCombosEqual(y, c)),
      );
    }
    result.set(def.id, combos);
  }
  return result;
}

// ---------------------------------------------------------------------------
// 匹配
// ---------------------------------------------------------------------------

interface PressedKeyState {
  code: string;
  meta: boolean;
  ctrl: boolean;
  alt: boolean;
  shift: boolean;
}

/** 双端共用的核心判定 —— renderer / main 两个入口都摊平到这里, 物理上不会漂移。 */
function matchesNormalized(pressed: PressedKeyState, comboValue: AppShortcutCombo): boolean {
  return (
    pressed.code === comboValue.code &&
    pressed.meta === comboValue.meta &&
    pressed.ctrl === comboValue.ctrl &&
    pressed.alt === comboValue.alt &&
    pressed.shift === comboValue.shift
  );
}

/** renderer KeyboardEvent 形态匹配 (结构化参数, 不依赖 DOM 类型)。 */
export function matchesKeyboardEvent(
  event: { code: string; metaKey: boolean; ctrlKey: boolean; altKey: boolean; shiftKey: boolean },
  comboValue: AppShortcutCombo,
): boolean {
  return matchesNormalized(
    {
      code: event.code,
      meta: event.metaKey,
      ctrl: event.ctrlKey,
      alt: event.altKey,
      shift: event.shiftKey,
    },
    comboValue,
  );
}

/** main 进程 before-input-event Input 形态匹配。 */
export function matchesElectronInput(
  input: { code: string; meta: boolean; control: boolean; alt: boolean; shift: boolean },
  comboValue: AppShortcutCombo,
): boolean {
  return matchesNormalized(
    {
      code: input.code,
      meta: input.meta,
      ctrl: input.control,
      alt: input.alt,
      shift: input.shift,
    },
    comboValue,
  );
}

export function matchesAnyCombo<E>(
  event: E,
  combos: AppShortcutCombo[] | undefined,
  matcher: (event: E, comboValue: AppShortcutCombo) => boolean,
): boolean {
  if (!combos || combos.length === 0) return false;
  return combos.some((c) => matcher(event, c));
}

// ---------------------------------------------------------------------------
// Electron accelerator 转换
// ---------------------------------------------------------------------------

/** code → Electron accelerator key 部分的显式映射 (仅可安全映射的键)。 */
const ACCELERATOR_KEY_BY_CODE: Record<string, string> = {
  Comma: ',',
  Period: '.',
  Semicolon: ';',
  Quote: "'",
  Slash: '/',
  Backslash: '\\',
  BracketLeft: '[',
  BracketRight: ']',
  Backquote: '`',
  Minus: '-',
  Equal: '=',
  Space: 'Space',
  Tab: 'Tab',
  Enter: 'Enter',
  Escape: 'Esc',
  Backspace: 'Backspace',
  Delete: 'Delete',
  Home: 'Home',
  End: 'End',
  PageUp: 'PageUp',
  PageDown: 'PageDown',
  ArrowUp: 'Up',
  ArrowDown: 'Down',
  ArrowLeft: 'Left',
  ArrowRight: 'Right',
};

/**
 * combo → Electron accelerator 字符串。无法映射的 code 返回 null: 该组合的
 * 菜单项静默降级为无 accelerator (点击仍可用), 实际按键由匹配路径生效。
 */
export function comboToElectronAccelerator(
  comboValue: AppShortcutCombo,
  platform: string,
): string | null {
  const keyPart = acceleratorKeyForCode(comboValue.code);
  if (!keyPart) return null;
  const parts: string[] = [];
  if (comboValue.ctrl) parts.push('Ctrl');
  if (comboValue.alt) parts.push('Alt');
  if (comboValue.shift) parts.push('Shift');
  if (comboValue.meta) parts.push(platform === 'darwin' ? 'Command' : 'Super');
  parts.push(keyPart);
  return parts.join('+');
}

function acceleratorKeyForCode(code: string): string | null {
  const letter = code.match(/^Key([A-Z])$/)?.[1];
  if (letter) return letter;
  const digit = code.match(/^Digit([0-9])$/)?.[1];
  if (digit) return digit;
  if (/^F([1-9]|1[0-9]|2[0-4])$/.test(code)) return code;
  return ACCELERATOR_KEY_BY_CODE[code] ?? null;
}

// ---------------------------------------------------------------------------
// 显示格式化
// ---------------------------------------------------------------------------

/** code → 人类可读键名 (显示用)。 */
const DISPLAY_KEY_LABELS: Record<string, string> = {
  Comma: ',',
  Period: '.',
  Semicolon: ';',
  Quote: "'",
  Slash: '/',
  Backslash: '\\',
  BracketLeft: '[',
  BracketRight: ']',
  Backquote: '`',
  Minus: '-',
  Equal: '=',
  Space: 'Space',
  Tab: 'Tab',
  Enter: 'Enter',
  Escape: 'Esc',
  Backspace: 'Backspace',
  Delete: 'Delete',
  Home: 'Home',
  End: 'End',
  PageUp: 'PgUp',
  PageDown: 'PgDn',
  ArrowUp: '↑',
  ArrowDown: '↓',
  ArrowLeft: '←',
  ArrowRight: '→',
  NumpadAdd: 'Num +',
  NumpadSubtract: 'Num -',
  Numpad0: 'Num 0',
};

/**
 * 跨平台显示格式化: mac 用 ⌃⌥⇧⌘ 无分隔符 (Apple 惯例顺序), 其它平台
 * Ctrl+Alt+Shift+Meta+Key。与 RolePillDropdown 既有的 '⌘N' / 'Ctrl+N' 呈现一致。
 */
export function formatAppShortcutCombo(comboValue: AppShortcutCombo, platform: string): string {
  const keyLabel = displayKeyForCode(comboValue.code, comboValue.key);
  if (platform === 'darwin') {
    const parts: string[] = [];
    if (comboValue.ctrl) parts.push('⌃');
    if (comboValue.alt) parts.push('⌥');
    if (comboValue.shift) parts.push('⇧');
    if (comboValue.meta) parts.push('⌘');
    parts.push(keyLabel);
    return parts.join('');
  }
  const parts: string[] = [];
  if (comboValue.ctrl) parts.push('Ctrl');
  if (comboValue.alt) parts.push('Alt');
  if (comboValue.shift) parts.push('Shift');
  if (comboValue.meta) parts.push('Meta');
  parts.push(keyLabel);
  return parts.join('+');
}

function displayKeyForCode(code: string, key?: string): string {
  const explicit = DISPLAY_KEY_LABELS[code];
  if (explicit) return explicit;
  const letter = code.match(/^Key([A-Z])$/)?.[1];
  if (letter) return letter;
  const digit = code.match(/^Digit([0-9])$/)?.[1];
  if (digit) return digit;
  if (/^F([1-9]|1[0-9]|2[0-4])$/.test(code)) return code;
  if (key && key.length === 1 && key !== ' ') return key.toUpperCase();
  return key || code;
}

// ---------------------------------------------------------------------------
// 录制与合法性
// ---------------------------------------------------------------------------

const MODIFIER_CODES = new Set([
  'AltLeft',
  'AltRight',
  'ControlLeft',
  'ControlRight',
  'MetaLeft',
  'MetaRight',
  'ShiftLeft',
  'ShiftRight',
  'Fn',
  'FnLock',
  'CapsLock',
]);

/** 设置页录制用: 纯修饰键事件返回 null (等用户按出主键)。 */
export function createAppShortcutComboFromEvent(event: {
  code: string;
  key: string;
  metaKey: boolean;
  ctrlKey: boolean;
  altKey: boolean;
  shiftKey: boolean;
}): AppShortcutCombo | null {
  if (!event.code || MODIFIER_CODES.has(event.code)) return null;
  return {
    code: event.code,
    key: event.key,
    meta: event.metaKey,
    ctrl: event.ctrlKey,
    alt: event.altKey,
    shift: event.shiftKey,
  };
}

/** Shift 单修饰时允许的非打印键 (Shift+字母/数字是正常输入, 不许占用)。 */
const SHIFT_ONLY_ALLOWED_CODES = /^(Tab|ArrowUp|ArrowDown|ArrowLeft|ArrowRight|Home|End|PageUp|PageDown|F([1-9]|1[0-9]|2[0-4]))$/;

/**
 * 裸键限制: 无修饰键仅允许 F1-F24; 仅 Shift 时只允许非打印键 (如 Shift+Tab);
 * 含 meta/ctrl/alt 任意一个即合法。
 */
export function isAppShortcutComboBindable(comboValue: AppShortcutCombo): boolean {
  if (comboValue.meta || comboValue.ctrl || comboValue.alt) return true;
  if (comboValue.shift) return SHIFT_ONLY_ALLOWED_CODES.test(comboValue.code);
  return /^F([1-9]|1[0-9]|2[0-4])$/.test(comboValue.code);
}

/** 单修饰 (mac ⌘ / 其它 Ctrl) + 这些键是所有应用的编辑惯例键, 全局占用会让别的应用失灵。 */
const GLOBAL_EDITING_CODES = new Set(['KeyA', 'KeyC', 'KeyV', 'KeyX', 'KeyY', 'KeyZ']);

/**
 * global scope 条目的额外约束: 必须能表达为 Electron accelerator (globalShortcut
 * 只认 accelerator, 表达不了 = 绑定了也永远不触发), 且不得占用编辑惯例键 ——
 * 全局快捷键会在所有应用里截走按键。系统保留键另由 keyboardReserved 判定。
 */
export function isGlobalAppShortcutComboUsable(
  comboValue: AppShortcutCombo,
  platform: string,
): boolean {
  if (comboToElectronAccelerator(comboValue, platform) === null) return false;
  const editingModifier = platform === 'darwin' ? comboValue.meta : comboValue.ctrl;
  const otherModifiers =
    platform === 'darwin'
      ? comboValue.ctrl || comboValue.alt || comboValue.shift
      : comboValue.meta || comboValue.alt || comboValue.shift;
  return !(editingModifier && !otherModifiers && GLOBAL_EDITING_CODES.has(comboValue.code));
}

export function appShortcutCombosEqual(a: AppShortcutCombo, b: AppShortcutCombo): boolean {
  return (
    a.code === b.code &&
    a.meta === b.meta &&
    a.ctrl === b.ctrl &&
    a.alt === b.alt &&
    a.shift === b.shift
  );
}

const OVERLAPPING_SCOPE_PAIRS = new Set(['browser:workdir-doc', 'composer:workdir-doc']);

/** 冲突检测域判定: app / global 与一切重叠; workdir-doc 与 browser / composer 同屏重叠。 */
export function appShortcutScopesOverlap(a: AppShortcutScope, b: AppShortcutScope): boolean {
  if (a === 'app' || b === 'app' || a === 'global' || b === 'global' || a === b) return true;
  const pair = [a, b].sort().join(':');
  return OVERLAPPING_SCOPE_PAIRS.has(pair);
}

/**
 * 跨 id 冲突检测: 给 id 绑 comboValue 时, 是否与其它 id 在重叠 scope 域内的
 * 生效组合 (默认 + overrides 合并后) 撞键。返回占用者 id, 无冲突返回 null。
 * renderer 设置页预检与 main store 写入兜底共用本函数, 校验口径不漂移。
 */
export function findAppShortcutConflict(
  id: AppShortcutId,
  comboValue: AppShortcutCombo,
  overrides: AppShortcutOverrides,
  platform: string,
): AppShortcutId | null {
  const selfDef = DEFINITION_MAP.get(id);
  if (!selfDef) return null;
  const effective = getEffectiveAppShortcuts(overrides, platform);
  for (const def of APP_SHORTCUT_DEFINITIONS) {
    if (def.id === id) continue;
    if (!appShortcutScopesOverlap(selfDef.scope, def.scope)) continue;
    // 未被 override 的让位槽位默认不构成占用: 用户显式改绑获胜 ——
    // getEffectiveAppShortcuts 会让该槽位的默认让位。否则用户想绑这些
    // 组合时会被一个设置页里看不到、也无法解绑的条目永久卡死。范围严格
    // 限定 yieldsToUserBindings, 不含 save-file 等惯例隐藏键 (那些仍占用,
    // 新绑定照常报冲突)。
    if (def.yieldsToUserBindings && overrides[def.id] === undefined) continue;
    const combos = effective.get(def.id);
    if (combos?.some((c) => appShortcutCombosEqual(c, comboValue))) return def.id;
  }
  return null;
}