一个全局键位管理器：所有快捷键走同一个监听器

/**
 * 全局唯一的键位监听器。所有快捷键都经过这里，按 action id 配置，可禁用、可改键。
 */

export interface Binding {
  keys: string;      // 如 'Alt+Q'、'Ctrl+Shift+K'、'Alt+`'
  enabled: boolean;
}
export type Bindings = Record<string, Binding>;

type Handler = (e: KeyboardEvent) => void | Promise<void>;

interface Parsed {
  alt: boolean; ctrl: boolean; shift: boolean; meta: boolean;
  key: string;
}

export function parseKeys(spec: string): Parsed {
  const out: Parsed = { alt: false, ctrl: false, shift: false, meta: false, key: '' };
  for (const raw of spec.split('+')) {
    const p = raw.trim().toLowerCase();
    if (p === 'alt' || p === 'option') out.alt = true;
    else if (p === 'ctrl' || p === 'control') out.ctrl = true;
    else if (p === 'shift') out.shift = true;
    else if (p === 'meta' || p === 'cmd' || p === 'win') out.meta = true;
    else if (p) out.key = p;
  }
  return out;
}

/** 归一化成「修饰键固定顺序 + 主键」，用于冲突检测：'q+alt' 与 'Alt+Q' 应视为同一个 */
export function normalizeKeys(spec: string): string {
  const p = parseKeys(spec);
  return [p.ctrl && 'ctrl', p.alt && 'alt', p.shift && 'shift', p.meta && 'meta', p.key]
    .filter(Boolean).join('+');
}

/** 主键匹配：先比 e.key，再用物理键位 e.code 兜底 */
function keyMatches(e: KeyboardEvent, key: string): boolean {
  const k = (e.key || '').toLowerCase();
  const code = e.code || '';
  if (key === '`' || key === 'backquote') return code === 'Backquote' || k === '`' || k === '~';
  if (key === '/' || key === 'slash') return code === 'Slash' || k === '/';
  if (k === key) return true;
  // ★ Alt / Option 组合在某些平台和键盘布局下，e.key 会变成别的字符（如 Mac 上 Alt+Q → 'œ'），
  //   单字母和数字用物理键位兜底
  if (/^[a-z]$/.test(key)) return code === `Key${key.toUpperCase()}`;
  if (/^[0-9]$/.test(key)) return code === `Digit${key}`;
  return false;
}

export function matches(e: KeyboardEvent, spec: string): boolean {
  const p = parseKeys(spec);
  if (!p.key) return false;
  return p.alt === e.altKey && p.ctrl === e.ctrlKey
    && p.shift === e.shiftKey && p.meta === e.metaKey
    && keyMatches(e, p.key);
}

export class KeybindingManager {
  private handlers = new Map<string, { handler: Handler; preventDefault: boolean }>();
  private installed = false;
  private attachedDocs = new WeakSet<Document>();
  /** ★ 同一个事件可能被多个监听点看到（见 attachIframes），只处理一次 */
  private handled = new WeakSet<Event>();

  constructor(private getBindings: () => Bindings) {}

  register(id: string, handler: Handler, preventDefault = true): void {
    this.handlers.set(id, { handler, preventDefault });
  }

  /** 在「每一个 frame」里都调用：焦点可能落在任意 iframe 里 */
  install(win: Window = window): void {
    if (this.installed) return;
    this.installed = true;
    win.addEventListener('keydown', (e) => this.dispatch(e), true);   // 捕获阶段，先于宿主
    this.attachIframes(win.document);
  }

  /**
   * 焦点在 iframe 里时，keydown 不会冒泡到外层 window。
   * 所以给每个同源 iframe 的 document 也挂一份（跨域的会抛 SecurityError，忽略）。
   */
  private attachIframes(doc: Document): void {
    const tryAttach = () => {
      doc.querySelectorAll('iframe').forEach((f) => {
        let d: Document | null = null;
        try { d = f.contentDocument; } catch { return; }
        if (!d || this.attachedDocs.has(d)) return;
        d.addEventListener('keydown', (e) => this.dispatch(e as KeyboardEvent), true);
        this.attachedDocs.add(d);
      });
    };
    tryAttach();
    // iframe 是异步出现的；回调只做廉价检查
    new MutationObserver(tryAttach).observe(doc.body ?? doc.documentElement, {
      childList: true, subtree: true,
    });
  }

  dispatch(e: KeyboardEvent): void {
    if (this.handled.has(e)) return;
    const bindings = this.getBindings();
    for (const [id, reg] of this.handlers) {
      const b = bindings[id];
      if (!b?.enabled || !matches(e, b.keys)) continue;
      this.handled.add(e);
      if (reg.preventDefault) {
        e.preventDefault();
        e.stopPropagation();
      }
      void reg.handler(e);
      return;                        // 一个按键只触发一个动作
    }
  }

  /** 给设置页用：找出被多个动作占用的组合键 */
  static findConflicts(bindings: Bindings): Array<[string, string[]]> {
    const bucket = new Map<string, string[]>();
    for (const [id, b] of Object.entries(bindings)) {
      if (!b.enabled || !b.keys.trim()) continue;
      const k = normalizeKeys(b.keys);
      bucket.set(k, [...(bucket.get(k) ?? []), id]);
    }
    return [...bucket.entries()].filter(([, ids]) => ids.length > 1);
  }
}