Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

29.8 KB
Raw Blame
import { IS_MAC } from '@core/constant/isMac';
import { hotkeyScopeNeutralSelector } from '@core/dom-selectors';
import { isTouchDevice } from '@core/mobile/isTouchDevice';
import { isEditableInput } from '@core/util/isEditableInput';
import { Telemetry } from '@macro-inc/observability';

import { getOwner, onCleanup, onMount } from 'solid-js';
import {
  EVENT_MODIFIER_KEYS,
  EVENT_MODIFIER_NAME_MAP,
  EVENT_TO_HOTKEY_NAME_MAP,
  HOTKEY_TO_EVENT_NAME_MAP,
  MODIFIER_LIST_MAC,
  MODIFIER_LIST_NON_MAC,
} from './constants';
import {
  activeScope,
  findLastLiveActiveDOMScope,
  hotkeyScopeTree,
  hotkeysAwaitingKeyUp,
  pressedKeys,
  setActiveScope,
  setHotkeyTokenMap,
  setPressedKeys,
} from './state';
import {
  HOTKEY_PRIORITY_DEFAULT,
  type HotkeyCommand,
  type HotkeyGroup,
  type HotkeyInterceptorContext,
  type HotkeyRegistrationOptions,
  isBaseKeyboardValue,
  type KeypressContext,
  type RegisterHotkeyReturn,
  type ScopeNode,
} from './types';
import {
  activateClosestDOMScope,
  findClosestParentScopeElement,
  findClosestParentScopeId,
  getCommandsForHotkey,
  getKeyString,
  getScopeId,
  normalizeEventKeyPress,
  prettyPrintHotkeyString,
  registerScope,
  removeCommandsFromTokenMap,
  removeScope,
  runCommand,
} from './utils';

/**
 * Registers a keyboard shortcut to a particular, existing scope.
 *
 * Use this to bind one or more hotkeys to a scope and provide the command's
 * behavior and metadata.
 *
 * @param args - Options to configure the hotkey registration
 * @param args.hotkeyToken - Unique identifier for this hotkey within its
 * scope. Used to look up the hotkey for UI elements.
 * @param args.hotkey - Keyboard shortcut keys, e.g. 'j', 'cmd+j', or
 * 'opt+shift+j'. We use Mac modifier abbreviations ('ctrl', 'opt', 'shift',
 * 'cmd'). Modifiers must be listed in this order: 'ctrl', 'opt', 'shift',
 * 'cmd'. 'cmd' will be translated to 'ctrl' for non-Mac users. For this
 * reason, you should not use both 'cmd' and 'ctrl' in your hotkeys. Can be a
 * single hotkey or an array of hotkeys.
 * @param args.condition - Optional condition to check if the hotkey command
 * should run. Checked on keydown/keyup. If this is reactive, any hotkey UI
 * that displays based on this condition will be reactively updated.
 * @param args.scopeId - The scopeId where this hotkey is active.
 * @param args.description - Human readable description of what the hotkey
 * does. Keep it short (around three words). Can be either a string or a callback that returns a string.
 * @param args.keyDownHandler - Function called when the hotkey is pressed. If
 * it returns true, the event will prevent default and stop propagation.
 * @param args.keyUpHandler - Optional function called when the hotkey is
 * released. This will be called even if the scope is no longer active, iff the
 * scope was active when the hotkey was initially pressed.
 * @param args.activateCommandScope - If true, pressing the hotkey will
 * activate a command scope. The returned object will include the created scope
 * id as `commandScopeId`.
 * @param args.runWithInputFocused - If true, the keyDownHandler will be run
 * even if an input is focused.
 * @param args.displayPriority - The priority of the command for ordering
 * hotkey display UI. 1 is the lowest priority, 10 is the highest.
 * @param args.hide - If true, hotkey command can be hidden from the UI. It
 * will still run, but may not be displayed. Can be either a boolean or a
 * function that returns a boolean for reactive behavior.
 * @param args.icon - Optional icon to display in the command palette.
 * @param args.tags - Optional tags for categorizing in the command palette.
 * @returns An object with a dispose function to clean up the hotkey
 * registration. If `activateCommandScope` is true, it also includes the
 * `commandScopeId`. When called under a reactive owner, the registration is
 * also disposed automatically with that owner — commands can attach to scopes
 * that outlive their registrant (block commands live on the split scope,
 * which survives split navigation), so they must not depend on scope teardown
 * for cleanup.
 *
 * @example
 * // Basic usage
 * registerHotkey({
 *   scopeId: 'my-scope',
 *   description: 'Delete item',
 *   hotkey: 'delete',
 *   keyDownHandler: () => true,
 * });
 */
export function registerHotkey(
  args: HotkeyRegistrationOptions & { activateCommandScope: true }
): RegisterHotkeyReturn & { commandScopeId: string };

export function registerHotkey(
  args: HotkeyRegistrationOptions
): RegisterHotkeyReturn;

export function registerHotkey(
  args: HotkeyRegistrationOptions
): RegisterHotkeyReturn {
  const {
    hotkey,
    condition,
    scopeId,
    description,
    keyDownHandler,
    keyUpHandler,
    activateCommandScope,
    activateCommandScopeId: providedCommandScopeId,
    runWithInputFocused,
    hotkeyToken,
    displayPriority,
    handlerPriority,
    registrationType = 'override',
    hide,
    icon,
    commandPaletteIcon,
    displayComponent,
    onHighlight,
    onHighlightEnd,
    tags,
    keywords,
    sheetSection,
    surfaceNestedCommands,
    shouldReturnFocusOnClose,
    proxiedHotkey,
    disposeWithOwner,
  } = args;

  const noopDisposer: RegisterHotkeyReturn = {
    dispose: () => {},
    hotkey: () => undefined,
    withGroup: (group) => {
      group.add(noopDisposer);
      return noopDisposer;
    },
  };

  if (!scopeId) {
    Telemetry.error(
      new Error('Scope ID is required for hotkey registration.'),
      {
        scopeId,
      }
    );
    return noopDisposer;
  }
  const scopeNode = hotkeyScopeTree.get(scopeId);
  if (!scopeNode) {
    Telemetry.error(new Error('Scope ID not found.'), {
      scopeId,
    });
    return noopDisposer;
  }

  // Convert single hotkey to array for consistent handling
  const hotkeys = hotkey && !Array.isArray(hotkey) ? [hotkey] : hotkey;

  // Tokens are shared across scopes on purpose (a list and an open entity
  // both bind entity.step.end), and getActiveCommandByToken resolves them by
  // the active branch. Only a same-token command in this scope is a conflict.
  const existingCommand = hotkeyToken
    ? scopeNode.commands.find((c) => c.hotkeyToken === hotkeyToken)
    : undefined;
  if (existingCommand && hotkeys && existingCommand.hotkeys) {
    // Yes, you should be able to register multiple hotkeys with the same token. But if you do this, they should be "the same" hotkey.
    // Here we check if the existing hotkey strings are the same as the new hotkey strings. This probably isn't exactly what you'd want to check (it especially won't be right if the commmands do not have hotkey strings), but is close enough for now.
    const existingHotkeys = existingCommand.hotkeys;
    if (
      existingHotkeys.length !== hotkeys?.length ||
      !existingHotkeys.every((el, i) => el === hotkeys[i])
    ) {
      Telemetry.warn(
        `Hotkey token "${hotkeyToken}" is already registered with a different command. ` +
          `Existing: ${existingCommand.description}, New: ${description}. ` +
          `This is likely a bug, please fix it. `,
        {
          error: 'Hotkey token already registered with a different command',
        }
      );
    }
  }

  let commandScopeId: string | undefined;
  // If a specific command scope ID is provided, use it instead of creating a new one
  if (providedCommandScopeId) {
    const existingScope = hotkeyScopeTree.get(providedCommandScopeId);
    if (!existingScope) {
      Telemetry.error(new Error('Provided command scope ID not found.'), {
        providedCommandScopeId,
      });
      return noopDisposer;
    }
    if (existingScope.type !== 'command') {
      Telemetry.error(new Error('Provided scope is not a command scope.'), {
        providedCommandScopeId,
        scopeType: existingScope.type,
      });
      return noopDisposer;
    }
    commandScopeId = providedCommandScopeId;
  } else if (activateCommandScope) {
    commandScopeId = getScopeId('command-scope-' + scopeId);
    // When a command scope is registered, its parent scope is set as the scopeId of the registered hotkey. It will be registered as a child of that scope. When the command scope is activated, its parent scope will get set to whatever scope is active where it was called, so that when the command scope is deactivated, it willl return to the correct scope.
    registerScope({
      parentScopeId: scopeId,
      scopeId: commandScopeId,
      type: 'command',
      activationKeys: hotkeys,
    });
  }

  const command: HotkeyCommand = {
    hotkeyToken,
    scopeId,
    registrationType,
    hotkeys,
    condition,
    description,
    keyDownHandler,
    keyUpHandler,
    activateCommandScopeId: commandScopeId,
    runWithInputFocused: runWithInputFocused ?? false,
    displayPriority: displayPriority ?? 0,
    handlerPriority: handlerPriority ?? HOTKEY_PRIORITY_DEFAULT,
    hide,
    icon,
    commandPaletteIcon,
    displayComponent,
    onHighlight,
    onHighlightEnd,
    tags,
    keywords,
    sheetSection,
    surfaceNestedCommands,
    shouldReturnFocusOnClose,
    proxiedHotkey,
  };

  // An override re-registration of the same logical command — same token in
  // this scope — replaces the old registration outright instead of stacking:
  // persistent commands (disposeWithOwner: false) re-register on every mount
  // of their view and must not accumulate eclipsed copies.
  if (registrationType === 'override' && hotkeyToken) {
    const replaced: HotkeyCommand[] = [];
    for (let i = scopeNode.commands.length - 1; i >= 0; i--) {
      const existingCommand = scopeNode.commands[i];
      if (existingCommand && existingCommand.hotkeyToken === hotkeyToken) {
        replaced.push(existingCommand);
        scopeNode.commands.splice(i, 1);
      }
    }
    if (replaced.length > 0) {
      setHotkeyTokenMap((prev) => removeCommandsFromTokenMap(prev, replaced));
    }
  }

  if (hotkeyToken) {
    setHotkeyTokenMap((prev) => {
      const newMap = new Map(prev);
      const existingCommands = newMap.get(hotkeyToken) || [];
      newMap.set(hotkeyToken, [...existingCommands, command]);
      return newMap;
    });
  }

  // Commands append in registration order. An 'override' command eclipses
  // the commands registered before it on its keys (see getCommandsForHotkey)
  // rather than destroying them, so disposing it restores whatever it
  // displaced — a block taking over a split-scope key does not permanently
  // disable it.
  scopeNode.commands.push(command);

  const primaryHotkey = hotkeys?.[0];
  const prettyHotkey = primaryHotkey
    ? prettyPrintHotkeyString(primaryHotkey)
    : undefined;

  // Create disposer object
  let disposed = false;
  const disposer: RegisterHotkeyReturn = {
    hotkey: () => prettyHotkey,
    dispose: () => {
      // Idempotent: manual disposal (groups, effect re-runs) and the
      // owner-bound auto-dispose below may both fire.
      if (disposed) return;
      disposed = true;

      // Remove from hotkey token map if it exists
      if (hotkeyToken) {
        setHotkeyTokenMap((prev) =>
          removeCommandsFromTokenMap(prev, [command])
        );
      }

      // Remove this specific command from its scope
      const scope = hotkeyScopeTree.get(scopeId);
      if (scope) {
        const idx = scope.commands.indexOf(command);
        if (idx !== -1) {
          scope.commands.splice(idx, 1);
        }
      }

      // Remove command scope only if we created it (not if we're using a shared one)
      if (commandScopeId && !providedCommandScopeId) {
        removeScope(commandScopeId);
      }
    },
    commandScopeId,
    withGroup: (group) => {
      group.add(disposer);
      return disposer;
    },
  };

  // A registration made under a reactive owner must not outlive it: the
  // target scope can persist past the registrant (the split scope survives
  // split navigation), and a leaked command would keep running with closures
  // over unmounted state. `disposeWithOwner: false` opts out for commands
  // meant to persist past their registrant (see HotkeyRegistrationOptions).
  if (disposeWithOwner !== false && getOwner()) {
    onCleanup(() => disposer.dispose());
  }

  return disposer;
}

/**
 * Creates a group for collecting hotkey registrations and disposing them all at once.
 *
 * @returns A group object with `add` and `dispose` methods
 *
 * @example
 * ```tsx
 * const group = createHotkeyGroup();
 *
 * // Add registrations using group.add()
 * group.add(registerHotkey({
 *   scopeId: 'my-scope',
 *   description: 'Delete item',
 *   hotkey: 'delete',
 *   keyDownHandler: () => true,
 * }));
 *
 * // Or use .withGroup() on the registration
 * registerHotkey({
 *   scopeId: 'my-scope',
 *   description: 'Copy item',
 *   hotkey: 'cmd+c',
 *   keyDownHandler: () => true,
 * }).withGroup(group);
 *
 * // Access commandScopeId naturally
 * const { commandScopeId } = group.add(registerHotkey({
 *   scopeId: 'my-scope',
 *   description: 'Open menu',
 *   hotkey: 'cmd+k',
 *   activateCommandScope: true,
 *   keyDownHandler: () => true,
 * }));
 *
 * group.add(registerHotkey({
 *   scopeId: commandScopeId,
 *   description: 'Menu option',
 *   hotkey: '1',
 *   keyDownHandler: () => true,
 * }));
 *
 * // Dispose all at once
 * onCleanup(() => group.dispose());
 * ```
 */
export function createHotkeyGroup(): HotkeyGroup {
  const disposers: (() => void)[] = [];

  return {
    add: <T extends RegisterHotkeyReturn>(registration: T): T => {
      disposers.push(() => registration.dispose());
      return registration;
    },
    addDisposer: (dispose) => {
      disposers.push(dispose);
    },
    dispose: () => {
      for (const fn of disposers) {
        fn();
      }
      disposers.length = 0;
    },
  };
}

// Variables for tracking event propagation
let scopeActivatedByFocusIn = false;

/**
 * Attaches hotkeys to a DOM element. Manages scope activation and deactivation based on focus events.
 * This is the correct way to attach hotkeys to a block.
 * @param {string} scopePrefix - Optional scope prefix for debugging purposes.
 * @param {boolean} detachedScope - If true, the scope will be attached directly to global scope.
 * @returns {[attachFn: (el: Element) => void, scopeId: string]} A tuple containing:
 *   - attachFn: Function to attach hotkey handlers to a DOM element
 *   - scopeId: The unique scope identifier that can be used with registerHotkey
 *
 *  * @example
 * ```tsx
 * function MyComponent() {
 *   const [attachHotkeys, scope] = useHotkeyDOMScope('mycomponent');
 *
 *   onMount(() => {
 *     attachHotkeys(ref()!);
 *   });
 *
 *   registerHotkey('delete', scope, 'Delete item', handleDelete);
 *
 *   return <div ref={ref}>...</div>;
 * }
 * ```
 */
export function useHotkeyDOMScope(
  scopePrefix?: string,
  detachedScope: boolean = false
): [(el: Element) => void, string] {
  const scopeId = getScopeId(scopePrefix);
  // Initially register the scope as a child of the global scope.
  // Once we attach the scope to a DOM element, we will update the parent scope to the closest parent scope, as well as updating the element in the ScopeNode.
  registerScope({
    parentScopeId: detachedScope ? undefined : 'global',
    scopeId,
    type: 'dom',
    detached: detachedScope,
  });

  const handleFocusIn = (e: Event) => {
    window.clearTimeout(focusoutTimoutId);

    // just in case focusin fires before focusout
    window.setTimeout(() => {
      window.clearTimeout(focusoutTimoutId);
    });

    const scopeNode = hotkeyScopeTree.get(scopeId);
    if (scopeNode && !scopeActivatedByFocusIn) {
      setActiveScope(scopeId);
      if (e.currentTarget instanceof Element) {
        repairScopeBranch(scopeNode, e.currentTarget);
      }
      scopeActivatedByFocusIn = true;
    }
  };

  // Runs up the DOM tree, repairing the scope tree parent/child relationship of each DOM scope parent found.
  const repairScopeBranch = (scopeNode: ScopeNode, scopeDOM: Element) => {
    let currentScope = scopeNode;
    let currentDOM: Element | null | undefined = scopeDOM;
    while (currentScope.scopeId !== 'global' && currentDOM) {
      // If the scope is detached, we can stop.
      if (currentScope.detached) {
        break;
      }
      const parentScopeId = findClosestParentScopeId(currentDOM);
      const parentScope = hotkeyScopeTree.get(parentScopeId);
      if (!parentScope) break;
      parentScope.childScopeIds.push(currentScope.scopeId);
      if (currentScope.type === 'dom') {
        currentScope.parentScopeId = parentScopeId;
      }
      currentScope = parentScope;
      const parentElement = findClosestParentScopeElement(currentDOM);
      currentDOM = parentElement;
    }
  };

  const attachFn = (el: Element) => {
    if (!el)
      return console.error(
        'Trying to attach hotkeys to an element that does exist.'
      );
    const DOMScope = hotkeyScopeTree.get(scopeId);
    // Attach this scope to the closest parent scope.
    // Note: this only works in "ideal" circumstances, where children are attached sequentially after parents. This is not always the case.
    let parentScopeId;
    if (!detachedScope) {
      parentScopeId = findClosestParentScopeId(el);
      const parentScope = hotkeyScopeTree.get(parentScopeId);
      if (parentScope) {
        parentScope.childScopeIds.push(scopeId);
      }
    }
    if (DOMScope?.type === 'dom') {
      DOMScope.parentScopeId = parentScopeId;
    }

    el.addEventListener('focusin', handleFocusIn);

    const currentDataAttribute = el.getAttribute('data-hotkey-scope');
    if (currentDataAttribute) {
      Telemetry.error(
        `Attempting to attach ${scopeId} hotkey scope, but the specified element already has a hotkey scope attached to it. This is an error and will break the hotkey scope tree. Please use that scope, ${currentDataAttribute}, instead of inventing your own.`
      );
    }
    el.setAttribute('data-hotkey-scope', scopeId);

    onCleanup(() => {
      el.removeEventListener('focusin', handleFocusIn);
    });
  };

  onCleanup(() => {
    removeScope(scopeId);
  });

  return [attachFn, scopeId];
}

export function attachGlobalDOMScope(el: Element) {
  const handleFocusIn = (e: Event) => {
    window.clearTimeout(focusoutTimoutId);

    // just in case focusin fires before focusout
    window.setTimeout(() => {
      window.clearTimeout(focusoutTimoutId);
    });

    // Focus landing in a neutral region (e.g. the sidebar) must not flip the
    // scope to 'global': that would mute every split/block command just
    // because the user clicked chrome that lives outside the splits. Overlays
    // without a scope of their own (dialogs, menus) are not neutral on
    // purpose — activating 'global' is what mutes app hotkeys beneath them.
    const isNeutralTarget =
      e.target instanceof Element &&
      e.target.closest(hotkeyScopeNeutralSelector) !== null;

    if (!scopeActivatedByFocusIn) {
      if (isNeutralTarget) {
        // A neutral region preserves a live scope but must not preserve a
        // decayed one. Opening an overlay from the sidebar moves focus into
        // a body portal (activating 'global'), and closing it returns focus
        // to the trigger; overlays that own a scope (the launcher) also
        // remove it on close. When the current scope is 'global' or gone,
        // restore the most recent live DOM scope instead.
        const currentScopeId = activeScope();
        const currentIsLive =
          currentScopeId !== 'global' && hotkeyScopeTree.has(currentScopeId);
        if (!currentIsLive) {
          const lastLiveScope = findLastLiveActiveDOMScope();
          if (lastLiveScope) {
            setActiveScope(lastLiveScope);
          }
        }
      } else {
        setActiveScope('global');
      }
    }
    scopeActivatedByFocusIn = false;
  };

  el.addEventListener('focusin', handleFocusIn);

  const currentDataAttribute = el.getAttribute('data-hotkey-scope');
  if (currentDataAttribute) {
    Telemetry.error(
      `Attempting to attach global hotkey scope, but the specified element already has a hotkey scope attached to it. This is an error and will break the hotkey scope tree. Please use that scope, ${currentDataAttribute}, instead of inventing your own.`
    );
  }
  el.setAttribute('data-hotkey-scope', 'global');

  onCleanup(() => {
    el.removeEventListener('focusin', handleFocusIn);
  });
}

/**
 * Attaches global hotkey handlers to the document element.
 * @returns A function to subscribe to keypress events with full context information.
 */
export function useHotKeyRoot() {
  if (isTouchDevice()) {
    return;
  }

  let onKeypress: ((context: KeypressContext) => void)[] = [];
  let onHotkeyInterceptor: ((context: HotkeyInterceptorContext) => boolean)[] =
    [];

  // Synthetic keyboard events must not reach the hotkey system: several
  // components dispatch keydowns to drive Kobalte (e.g.
  // highlightFirstMenuItemOnOpen sends ArrowDown, with no paired keyup), and a
  // keydown without its keyup leaves a phantom key stuck in pressedKeys that
  // makes every subsequent plain-key hotkey resolve to e.g. 'arrowdown+j'
  // until a modifier keyup clears the set. Tests simulate keypresses with
  // dispatched (untrusted) events, so they stay exempt. Chrome autofill
  // dispatches trusted keydown/keyup events with no `key`; they are not key
  // presses either.
  const shouldIgnoreKeyEvent = (e: KeyboardEvent) =>
    typeof e.key !== 'string' ||
    (!e.isTrusted && import.meta.env.MODE !== 'test');

  const handleKeyDown = (e: KeyboardEvent) => {
    if (shouldIgnoreKeyEvent(e)) return;
    document.documentElement.dataset.modality = 'keyboard';
    const key = normalizeEventKeyPress(e);

    if (key === 'dead') return;

    if (!EVENT_MODIFIER_KEYS.has(key) && isBaseKeyboardValue(key)) {
      setPressedKeys((prev) => new Set([...prev, key]));
    }

    // Handle modifier keys. We iterate thru a list of possible modifier keys.
    // When not on mac, we disclude the 'meta' key, because we are treating the 'ctrl' on non-mac as equivalent to the 'meta' key on mac.
    (IS_MAC ? MODIFIER_LIST_MAC : MODIFIER_LIST_NON_MAC).forEach(
      (mod: keyof typeof EVENT_MODIFIER_NAME_MAP) => {
        const modHotkeyName =
          EVENT_TO_HOTKEY_NAME_MAP[EVENT_MODIFIER_NAME_MAP[mod]];
        if (e[mod] && !pressedKeys().has(modHotkeyName)) {
          setPressedKeys((prev) => new Set([...prev, modHotkeyName]));
        } else if (!e[mod] && pressedKeys().has(modHotkeyName)) {
          setPressedKeys(
            (prev) =>
              new Set(Array.from(prev).filter((k) => k !== modHotkeyName))
          );
        } else if (mod === 'metaKey' && e[mod]) {
          // If command key is pressed, clear all non-modifier keys except for key pressed in this event.
          // This is a necessary, defensive step because the OS captures the key-up events when you press, e.g. 'cmd+z'
          setPressedKeys(
            (prev) =>
              new Set(
                Array.from(prev).filter(
                  (k) => k in HOTKEY_TO_EVENT_NAME_MAP || k === key
                )
              )
          );
        }
      }
    );

    checkHotKeys(e);
  };

  const handleKeyUp = (e: KeyboardEvent) => {
    if (shouldIgnoreKeyEvent(e)) return;
    const key = normalizeEventKeyPress(e);

    // if we are releasing a modifier key, release all keys, because the user may have triggered some broswer or os shortcut
    // also addresses an underlying problem of modifiers sometimes getting bugged out
    if (EVENT_MODIFIER_KEYS.has(key)) {
      setPressedKeys(new Set<string>());
    } else {
      setPressedKeys(
        (prev) => new Set(Array.from(prev).filter((k) => k !== key))
      );
    }

    checkHotKeys(e);
  };

  // Clear all pressed keys when window loses focus
  const handleWindowBlur = () => {
    setPressedKeys(new Set<string>());
  };

  onMount(() => {
    document.addEventListener('keydown', handleKeyDown, { capture: true });
    document.addEventListener('keyup', handleKeyUp, { capture: true });
    window.addEventListener('blur', handleWindowBlur);
  });

  onCleanup(() => {
    document.removeEventListener('keydown', handleKeyDown, { capture: true });
    document.removeEventListener('keyup', handleKeyUp, { capture: true });
    window.removeEventListener('blur', handleWindowBlur);
  });

  const checkHotKeys = (e: KeyboardEvent) => {
    const scopeTree = hotkeyScopeTree;
    const currentScopeId = activeScope();
    const currentPressedKeys = pressedKeys();
    if (currentPressedKeys.size === 0) {
      return;
    }
    const isEditableFocused = isEditableInput(document.activeElement);
    if (!currentScopeId) {
      return Telemetry.error(
        new Error('Could not find current hotkey scope.'),
        {
          currentScopeId,
        }
      );
    }

    const pressedKeysString = getKeyString(currentPressedKeys);

    // Call hotkey interceptor handlers before command lookup
    // If any handler returns true, capture the event and skip normal processing
    const hotkeyInterceptorContext: HotkeyInterceptorContext = {
      pressedKeysString,
      pressedKeys: currentPressedKeys,
      event: e,
      activeScopeId: currentScopeId,
      isEditableFocused: isEditableFocused ?? false,
      eventType: e.type as 'keydown' | 'keyup',
    };

    for (const callback of onHotkeyInterceptor) {
      if (callback(hotkeyInterceptorContext)) {
        e.preventDefault();
        e.stopPropagation();
        return;
      }
    }

    let scopeNode = scopeTree.get(currentScopeId);
    let commandCaptured: HotkeyCommand | undefined;
    let commandScopeActivated = false;

    while (scopeNode) {
      const commands = getCommandsForHotkey(scopeNode, pressedKeysString);
      if (commands.length > 0) {
        // Sort commands by handlerPriority (higher priority first)
        const sortedCommands = [...commands].sort(
          (a, b) => (b.handlerPriority ?? 0) - (a.handlerPriority ?? 0)
        );

        // Run handlers in priority order
        for (const command of sortedCommands) {
          if (command.runWithInputFocused || !isEditableFocused) {
            const result = runCommand(
              command,
              e,
              pressedKeysString,
              scopeNode.scopeId
            );

            if (result.commandCaptured) {
              commandCaptured = result.commandCaptured;
            }
            if (result.commandScopeActivated) {
              commandScopeActivated = true;
            }

            // stops running handlers up the scope and laterally
            if (result.stopPropagation) {
              break;
            }
          }
        }
      }

      if (
        scopeNode.type === 'command' &&
        ![...currentPressedKeys].some((key) =>
          ['cmd', 'ctrl', 'opt', 'shift'].includes(key)
        )
      ) {
        // if we're in a command scope, any non-modifier input should jettison us back to closest DOM scope
        activateClosestDOMScope();
      }

      if (commandCaptured || commandScopeActivated) {
        break;
      }

      // Move up to parent scope
      scopeNode = scopeNode.parentScopeId
        ? hotkeyScopeTree.get(scopeNode.parentScopeId)
        : undefined;
    }

    if (e.type === 'keyup') {
      // check if there are any keyUpHandlers that should be triggered.
      hotkeysAwaitingKeyUp.forEach((command) => {
        const key = command.hotkey.split('+').at(-1);
        const keyReleased = key && !currentPressedKeys.has(key);

        if (keyReleased) {
          command.command?.();
          hotkeysAwaitingKeyUp.splice(hotkeysAwaitingKeyUp.indexOf(command), 1);
        }
      });
    }

    // Build context object with all relevant information
    const context: KeypressContext = {
      pressedKeysString,
      pressedKeys: currentPressedKeys,
      event: e,
      activeScopeId: currentScopeId ?? null,
      isEditableFocused: isEditableFocused ?? false,
      commandScopeActivated,
      commandFound: !!commandCaptured,
      commandCaptured: commandCaptured,
      eventType: e.type as 'keydown' | 'keyup',
    };

    // Notify all subscribers with the context
    onKeypress.forEach((callback) => callback(context));
  };

  return {
    /**
     * Subscribe to keypress events with full context information.
     * Subscribers receive a context object containing all relevant information.
     *
     * @param callback - Function called on every keypress.
     * @returns A cleanup function to unsubscribe from the keypress events.
     *
     * @example
     * ```ts
     * subscribeToKeypress((context) => {
     *   // Only handle non-modifier keys without scope activation
     *   if (
     *     !context.commandScopeActivated &&
     *     ![...context.pressedKeys].every((key) =>
     *       ['cmd', 'ctrl', 'opt', 'shift'].includes(key)
     *     )
     *   ) {
     *     // Handle the keypress
     *   }
     * });
     * ```
     */
    subscribeToKeypress: (callback: (context: KeypressContext) => void) => {
      onKeypress.push(callback);
      return () => {
        onKeypress = onKeypress.filter((c) => c !== callback);
      };
    },

    /**
     * Subscribe to hotkey interceptor events BEFORE command lookup.
     * Return true from the callback to capture the event and prevent
     * normal hotkey command lookup and propagation.
     *
     * @param callback - Function called before hotkey command lookup.
     *   Return true to capture the event and skip normal processing.
     * @returns A cleanup function to unsubscribe.
     *
     * @example
     * ```ts
     * addHotkeyInterceptor((context) => {
     *   // Capture unregistered keys in a specific scope
     *   if (context.activeScopeId === 'my-command-scope') {
     *     return true; // Capture and prevent propagation
     *   }
     *   return false; // Let normal processing continue
     * });
     * ```
     */
    addHotkeyInterceptor: (
      callback: (context: HotkeyInterceptorContext) => boolean
    ) => {
      onHotkeyInterceptor.push(callback);
      return () => {
        onHotkeyInterceptor = onHotkeyInterceptor.filter((c) => c !== callback);
      };
    },
  };
}

// =========================================================================
// Focusout Timeout ID
// =========================================================================

let focusoutTimoutId = 0;