@pellux/goodvibes-tui 0.18.20 → 0.18.23

package/src/input/handler-shortcuts.ts

@@ -52,144 +52,157 @@ export function handleGlobalShortcutToken(
 ): boolean {
   if (token.type !== 'key') return false;
 
-  const kb = state.keybindingsManager;
-  if (kb.matches('copy-selection', token)) {
-    state.handleCopy();
+  // Fast-path: bare pageup/pagedown have no keybinding entry.
+  if (token.logicalName === 'pageup') {
+    state.scroll(-Math.max(1, viewportHeight - 2));
     return true;
   }
-  if (kb.matches('clear-cancel', token)) {
-    state.handleCtrlC();
+  if (token.logicalName === 'pagedown') {
+    state.scroll(Math.max(1, viewportHeight - 2));
     return true;
   }
+  // Bare escape is also not in the keybinding table.
   if (token.logicalName === 'escape' && !state.panelFocused) {
     state.handleEscape();
     return true;
   }
-  if (kb.matches('screen-clear', token)) {
-    state.commandContext?.clearScreen?.();
-    return true;
-  }
-  if (kb.matches('panel-close-all', token)) {
-    const pm = state.panelManager;
-    for (const p of pm.getAllOpen()) pm.close(p.id);
-    pm.hide();
-    state.requestRender();
-    return true;
-  }
-  if (kb.matches('panel-close', token)) {
-    const pm = state.panelManager;
-    const active = pm.getActivePanel();
-    if (active) {
-      pm.close(active.id);
+
+  // O(1) lookup via inverted map.
+  const kb = state.keybindingsManager;
+  const action = kb.lookup(token);
+
+  switch (action) {
+    case 'copy-selection':
+      state.handleCopy();
+      return true;
+
+    case 'clear-cancel':
+      state.handleCtrlC();
+      return true;
+
+    case 'screen-clear':
+      state.commandContext?.clearScreen?.();
+      return true;
+
+    case 'panel-close-all': {
+      const pm = state.panelManager;
+      for (const p of pm.getAllOpen()) pm.close(p.id);
+      pm.hide();
       state.requestRender();
+      return true;
     }
-    return true;
-  }
-  if (kb.matches('panel-picker', token)) {
-    state.commandContext?.openPanelPicker?.();
-    state.requestRender();
-    return true;
-  }
-  if (kb.matches('panel-tab-next', token)) {
-    state.cyclePanelTab('next');
-    return true;
-  }
-  if (kb.matches('panel-tab-prev', token)) {
-    state.cyclePanelTab('prev');
-    return true;
-  }
-  if (kb.matches('history-search', token)) {
-    state.historySearch.open(state.prompt);
-    state.requestRender();
-    return true;
-  }
-  if (kb.matches('search', token)) {
-    if (state.searchManager.active) state.searchManager.close();
-    else state.searchManager.open();
-    state.requestRender();
-    return true;
-  }
-  if (kb.matches('block-copy', token) && !state.commandMode) {
-    state.handleBlockCopy();
-    return true;
-  }
-  if (kb.matches('bookmark', token) && !state.commandMode) {
-    state.handleBookmark();
-    return true;
-  }
-  if (kb.matches('block-save', token) && !state.commandMode) {
-    state.handleBlockSave();
-    return true;
-  }
-  if (kb.matches('delete-word', token)) {
-    state.saveUndoState();
-    let pos = state.cursorPos;
-    while (pos > 0 && state.prompt[pos - 1] === ' ') pos--;
-    while (pos > 0 && state.prompt[pos - 1] !== ' ') pos--;
-    state.prompt = state.prompt.slice(0, pos) + state.prompt.slice(state.cursorPos);
-    state.cursorPos = pos;
-    state.ensureInputCursorVisible();
-    return true;
-  }
-  if (kb.matches('apply-diff-line-start', token)) {
-    if (!state.commandMode && state.handleDiffApply()) return true;
-    const info = state.getWrappedPromptInfo(state.contentWidth);
-    state.cursorPos = info.wrappedLines.length > 1 ? info.segments[info.cursorWrappedLine].rawStart : 0;
-    state.ensureInputCursorVisible();
-    return true;
-  }
-  if (kb.matches('next-error-line-end', token)) {
-    if (state.prompt === '' && !state.commandMode) {
-      const nextLine = state.conversationManager?.nextErrorLine(state.getScrollTop()) ?? -1;
-      if (nextLine >= 0) {
-        state.scroll(nextLine - state.getScrollTop());
+
+    case 'panel-close': {
+      const pm = state.panelManager;
+      const active = pm.getActivePanel();
+      if (active) {
+        pm.close(active.id);
         state.requestRender();
-        return true;
       }
+      return true;
     }
-    const info = state.getWrappedPromptInfo(state.contentWidth);
-    state.cursorPos = info.wrappedLines.length > 1
-      ? info.segments[info.cursorWrappedLine].rawStart + info.segments[info.cursorWrappedLine].length
-      : state.prompt.length;
-    state.ensureInputCursorVisible();
-    return true;
-  }
-  if (kb.matches('kill-line', token)) {
-    state.saveUndoState();
-    state.prompt = state.prompt.slice(0, state.cursorPos);
-    state.ensureInputCursorVisible();
-    return true;
-  }
-  if (kb.matches('clear-prompt', token)) {
-    state.saveUndoState();
-    state.prompt = '';
-    state.cursorPos = 0;
-    if (state.commandMode) {
-      state.commandMode = false;
-      state.autocomplete?.reset();
+
+    case 'panel-picker':
+      state.commandContext?.openPanelPicker?.();
+      state.requestRender();
+      return true;
+
+    case 'panel-tab-next':
+      state.cyclePanelTab('next');
+      return true;
+
+    case 'panel-tab-prev':
+      state.cyclePanelTab('prev');
+      return true;
+
+    case 'history-search':
+      state.historySearch.open(state.prompt);
+      state.requestRender();
+      return true;
+
+    case 'search':
+      if (state.searchManager.active) state.searchManager.close();
+      else state.searchManager.open();
+      state.requestRender();
+      return true;
+
+    case 'block-copy':
+      if (!state.commandMode) { state.handleBlockCopy(); return true; }
+      return false;
+
+    case 'bookmark':
+      if (!state.commandMode) { state.handleBookmark(); return true; }
+      return false;
+
+    case 'block-save':
+      if (!state.commandMode) { state.handleBlockSave(); return true; }
+      return false;
+
+    case 'delete-word': {
+      state.saveUndoState();
+      let pos = state.cursorPos;
+      while (pos > 0 && state.prompt[pos - 1] === ' ') pos--;
+      while (pos > 0 && state.prompt[pos - 1] !== ' ') pos--;
+      state.prompt = state.prompt.slice(0, pos) + state.prompt.slice(state.cursorPos);
+      state.cursorPos = pos;
+      state.ensureInputCursorVisible();
+      return true;
+    }
+
+    case 'apply-diff-line-start': {
+      if (!state.commandMode && state.handleDiffApply()) return true;
+      const info = state.getWrappedPromptInfo(state.contentWidth);
+      state.cursorPos = info.wrappedLines.length > 1 ? info.segments[info.cursorWrappedLine].rawStart : 0;
+      state.ensureInputCursorVisible();
+      return true;
     }
-    return true;
-  }
-  if (kb.matches('undo', token)) {
-    state.handleUndo();
-    return true;
-  }
-  if (kb.matches('redo', token)) {
-    state.handleRedo();
-    return true;
-  }
-  if (kb.matches('paste', token)) {
-    state.handlePaste();
-    return true;
-  }
-  if (token.logicalName === 'pageup') {
-    state.scroll(-Math.max(1, viewportHeight - 2));
-    return true;
-  }
-  if (token.logicalName === 'pagedown') {
-    state.scroll(Math.max(1, viewportHeight - 2));
-    return true;
-  }
 
-  return false;
+    case 'next-error-line-end': {
+      if (state.prompt === '' && !state.commandMode) {
+        const nextLine = state.conversationManager?.nextErrorLine(state.getScrollTop()) ?? -1;
+        if (nextLine >= 0) {
+          state.scroll(nextLine - state.getScrollTop());
+          state.requestRender();
+          return true;
+        }
+      }
+      const info = state.getWrappedPromptInfo(state.contentWidth);
+      state.cursorPos = info.wrappedLines.length > 1
+        ? info.segments[info.cursorWrappedLine].rawStart + info.segments[info.cursorWrappedLine].length
+        : state.prompt.length;
+      state.ensureInputCursorVisible();
+      return true;
+    }
+
+    case 'kill-line':
+      state.saveUndoState();
+      state.prompt = state.prompt.slice(0, state.cursorPos);
+      state.ensureInputCursorVisible();
+      return true;
+
+    case 'clear-prompt':
+      state.saveUndoState();
+      state.prompt = '';
+      state.cursorPos = 0;
+      if (state.commandMode) {
+        state.commandMode = false;
+        state.autocomplete?.reset();
+      }
+      return true;
+
+    case 'undo':
+      state.handleUndo();
+      return true;
+
+    case 'redo':
+      state.handleRedo();
+      return true;
+
+    case 'paste':
+      state.handlePaste();
+      return true;
+
+    default:
+      return false;
+  }
 }

package/src/input/handler.ts

@@ -81,6 +81,7 @@ import {
 } from './handler-picker-routes.ts';
 import { handleGlobalShortcutToken } from './handler-shortcuts.ts';
 import { feedInputTokens } from './handler-feed.ts';
+import { buildInitialFeedContext } from './feed-context-factory.ts';
 import { handlePanelIntegrationAction as runPanelIntegrationAction } from './panel-integration-actions.ts';
 import type { Panel } from '../panels/types.ts';
 import type { UiRuntimeServices } from '../runtime/ui-services.ts';
@@ -112,6 +113,8 @@ export class InputHandler {
   private pasteRegistry = new Map<string, string>();
   private nextPasteId = 1;
   private lastCtrlCTime = 0;
+  /** Long-lived feed context — reused across every feed() call to avoid per-keystroke allocation. */
+  private feedContext!: import('./handler-feed.ts').InputFeedContext;
   private commandRegistry: CommandRegistry | null = null;
   private commandContext: CommandContext | undefined = undefined;
   public autocomplete: AutocompleteEngine | null = null;
@@ -208,32 +211,110 @@ export class InputHandler {
     this.bookmarkModal = new BookmarkModal(uiServices.shell.bookmarkManager);
     this.sessionPickerModal = new SessionPickerModal(uiServices.sessions.sessionManager);
     this.profilePickerModal = new ProfilePickerModal(uiServices.shell.profileManager);
+    this.initFeedContext();
   }
 
   /**
-   * setHistory - Wire in the InputHistory instance.
-   * Optional; if not set, history navigation is disabled.
+   * initFeedContext — Build the long-lived InputFeedContext once via factory.
+   * See feed-context-factory.ts for full field documentation.
    */
-  public setHistory(history: InputHistory): void {
-    this.inputHistory = history;
+  private initFeedContext(): void {
+    this.feedContext = buildInitialFeedContext(
+      {
+        prompt: this.prompt, cursorPos: this.cursorPos, commandMode: this.commandMode,
+        panelFocused: this.panelFocused, indicatorFocused: this.indicatorFocused,
+        helpOverlayActive: this.helpOverlayActive, helpScrollOffset: this.helpScrollOffset,
+        shortcutsOverlayActive: this.shortcutsOverlayActive, shortcutsScrollOffset: this.shortcutsScrollOffset,
+        nextPasteId: this.nextPasteId, nextImageId: this.nextImageId,
+        mouseDownRow: this.mouseDownRow, mouseDownCol: this.mouseDownCol,
+        contentWidth: this.contentWidth, selectionCallback: this.selectionCallback,
+      },
+      {
+        selection: this.selection,
+        pasteRegistry: this.pasteRegistry,
+        imageRegistry: this.imageRegistry,
+        selectionModal: this.selectionModal,
+        bookmarkModal: this.bookmarkModal,
+        settingsModal: this.settingsModal,
+        sessionPickerModal: this.sessionPickerModal,
+        profilePickerModal: this.profilePickerModal,
+        historySearch: this.historySearch,
+        commandRegistry: this.commandRegistry,
+        commandContext: this.commandContext,
+        autocomplete: this.autocomplete,
+        filePicker: this.filePicker,
+        modelPicker: this.modelPicker,
+        processModal: this.processModal,
+        liveTailModal: this.liveTailModal,
+        agentDetailModal: this.agentDetailModal,
+        contextInspectorModal: this.contextInspectorModal,
+        blockActionsMenu: this.blockActionsMenu,
+        searchManager: this.searchManager,
+        modalStack: this.modalStack,
+        inputHistory: this.inputHistory,
+        conversationManager: this.conversationManager,
+        panelManager: this.uiServices.shell.panelManager,
+        keybindingsManager: this.uiServices.shell.keybindingsManager,
+        getHistory: this.getHistory,
+        getViewportHeight: this.getViewportHeight,
+        getScrollTop: this.getScrollTop,
+        scroll: this.scroll,
+        exitApp: this.exitApp,
+      },
+      {
+        modalOpened: (name: string) => this.modalOpened(name),
+        handleEscape: () => { this.handleEscape(); this.syncFeedContextMutableFields(); },
+        handleCopy: () => this.handleCopy(),
+        handleCtrlC: () => { this.handleCtrlC(); this.syncFeedContextMutableFields(); },
+        handleBlockCopy: () => this.handleBlockCopy(),
+        handleBookmark: () => this.handleBookmark(),
+        handleBlockSave: () => this.handleBlockSave(),
+        handleDiffApply: () => this.handleDiffApply(),
+        handleUndo: () => { this.handleUndo(); this.syncFeedContextMutableFields(); },
+        handleRedo: () => { this.handleRedo(); this.syncFeedContextMutableFields(); },
+        handlePaste: () => { this.handlePaste(); this.syncFeedContextMutableFields(); },
+        saveUndoState: () => this.saveUndoState(),
+        ensureInputCursorVisible: (contentWidth?: number) => this.ensureInputCursorVisible(contentWidth),
+        registerPaste: (content: string) => this.registerPaste(content),
+        executeBlockAction: (id: string) => this.executeBlockAction(id),
+        cyclePanelTab: (direction: 'next' | 'prev') => this.cyclePanelTab(direction),
+        onPanelInputConsumed: (activePanel: Panel | null, key: string) => this.handlePanelIntegrationAction(activePanel, key),
+        getWrappedPromptInfo: (contentWidth: number) => this.getWrappedPromptInfo(contentWidth),
+        moveCursorVertical: (direction: -1 | 1) => this.moveCursorVertical(direction),
+        handlePathCompletion: () => this.handlePathCompletion(),
+        handleBlockToggle: () => this.handleBlockToggle(),
+        findMarkerAtPos: (pos: number) => this.findMarkerAtPos(pos),
+        cleanupMarkerRegistry: (text: string) => this.cleanupMarkerRegistry(text),
+        expandPrompt: (text: string) => this.expandPrompt(text),
+      },
+    );
   }
 
-  /**
-   * setCommandRegistry - Wire in the slash command registry and context.
-   * Must be called before commands can be processed.
-   */
+  /** Sync mutable handler fields back into feedContext after in-feed mutations. */
+  private syncFeedContextMutableFields(): void {
+    const ctx = this.feedContext;
+    ctx.prompt = this.prompt; ctx.cursorPos = this.cursorPos;
+    ctx.commandMode = this.commandMode; ctx.panelFocused = this.panelFocused;
+    ctx.indicatorFocused = this.indicatorFocused;
+    ctx.helpOverlayActive = this.helpOverlayActive; ctx.helpScrollOffset = this.helpScrollOffset;
+    ctx.shortcutsOverlayActive = this.shortcutsOverlayActive; ctx.shortcutsScrollOffset = this.shortcutsScrollOffset;
+    ctx.selectionCallback = this.selectionCallback;
+    ctx.nextPasteId = this.nextPasteId; ctx.nextImageId = this.nextImageId;
+    ctx.mouseDownRow = this.mouseDownRow; ctx.mouseDownCol = this.mouseDownCol;
+  }
+
+  /** Wire in the InputHistory instance. Optional; disables history navigation if unset. */
+  public setHistory(history: InputHistory): void { this.inputHistory = history; }
+
+  /** Wire in the slash command registry and context. Must be called before commands work. */
   public setCommandRegistry(registry: CommandRegistry, context: CommandContext): void {
     this.commandRegistry = registry;
     this.commandContext = context;
     this.autocomplete = new AutocompleteEngine(registry);
   }
 
-  /**
-   * setConversationManager - Wire in the conversation manager for block copy/apply/collapse.
-   */
-  public setConversationManager(cm: ConversationManager): void {
-    this.conversationManager = cm;
-  }
+  /** Wire in the conversation manager for block copy/apply/collapse. */
+  public setConversationManager(cm: ConversationManager): void { this.conversationManager = cm; }
 
   /**
    * openSelection - Open the generic selection modal with a callback.
@@ -464,6 +545,7 @@ export class InputHandler {
 
   /**
    * feed - Process raw stdin data through the tokenizer.
+   * Reuses the long-lived this.feedContext to avoid per-keystroke object allocation.
    */
   public feed(data: string): void {
     const immediateRequestRender = this.requestRender;
@@ -479,111 +561,31 @@ export class InputHandler {
 
     this.requestRender = bufferedRequestRender;
     try {
-      let context!: import('./handler-feed.ts').InputFeedContext;
-      const syncFeedContextFromHandler = (): void => {
-        context.prompt = this.prompt;
-        context.cursorPos = this.cursorPos;
-        context.commandMode = this.commandMode;
-        context.panelFocused = this.panelFocused;
-        context.indicatorFocused = this.indicatorFocused;
-        context.helpOverlayActive = this.helpOverlayActive;
-        context.helpScrollOffset = this.helpScrollOffset;
-        context.shortcutsOverlayActive = this.shortcutsOverlayActive;
-        context.shortcutsScrollOffset = this.shortcutsScrollOffset;
-        context.selectionCallback = this.selectionCallback;
-        context.nextPasteId = this.nextPasteId;
-        context.nextImageId = this.nextImageId;
-        context.mouseDownRow = this.mouseDownRow;
-        context.mouseDownCol = this.mouseDownCol;
-      };
-
-      context = {
-        prompt: this.prompt,
-        cursorPos: this.cursorPos,
-        commandMode: this.commandMode,
-        panelFocused: this.panelFocused,
-        indicatorFocused: this.indicatorFocused,
-        helpOverlayActive: this.helpOverlayActive,
-        helpScrollOffset: this.helpScrollOffset,
-        shortcutsOverlayActive: this.shortcutsOverlayActive,
-        shortcutsScrollOffset: this.shortcutsScrollOffset,
-        nextPasteId: this.nextPasteId,
-        nextImageId: this.nextImageId,
-        mouseDownRow: this.mouseDownRow,
-        mouseDownCol: this.mouseDownCol,
-        contentWidth: this.contentWidth,
-        pasteRegistry: this.pasteRegistry,
-        imageRegistry: this.imageRegistry,
-        selection: this.selection,
-        selectionModal: this.selectionModal,
-        selectionCallback: this.selectionCallback,
-        bookmarkModal: this.bookmarkModal,
-        settingsModal: this.settingsModal,
-        sessionPickerModal: this.sessionPickerModal,
-        profilePickerModal: this.profilePickerModal,
-        historySearch: this.historySearch,
-        commandRegistry: this.commandRegistry,
-        commandContext: this.commandContext,
-        autocomplete: this.autocomplete,
-        filePicker: this.filePicker,
-        modelPicker: this.modelPicker,
-        processModal: this.processModal,
-        liveTailModal: this.liveTailModal,
-        agentDetailModal: this.agentDetailModal,
-        contextInspectorModal: this.contextInspectorModal,
-        blockActionsMenu: this.blockActionsMenu,
-        searchManager: this.searchManager,
-        modalStack: this.modalStack,
-        inputHistory: this.inputHistory,
-        conversationManager: this.conversationManager,
-        getHistory: this.getHistory,
-        getViewportHeight: this.getViewportHeight,
-        getScrollTop: this.getScrollTop,
-        scroll: this.scroll,
-        requestRender: bufferedRequestRender,
-        modalOpened: (name: string) => this.modalOpened(name),
-        handleEscape: () => {
-          this.handleEscape();
-          syncFeedContextFromHandler();
-        },
-        handleCopy: () => this.handleCopy(),
-        handleCtrlC: () => {
-          this.handleCtrlC();
-          syncFeedContextFromHandler();
-        },
-        handleBlockCopy: () => this.handleBlockCopy(),
-        handleBookmark: () => this.handleBookmark(),
-        handleBlockSave: () => this.handleBlockSave(),
-        handleDiffApply: () => this.handleDiffApply(),
-        handleUndo: () => {
-          this.handleUndo();
-          syncFeedContextFromHandler();
-        },
-        handleRedo: () => {
-          this.handleRedo();
-          syncFeedContextFromHandler();
-        },
-        handlePaste: () => {
-          this.handlePaste();
-          syncFeedContextFromHandler();
-        },
-        saveUndoState: () => this.saveUndoState(),
-        ensureInputCursorVisible: (contentWidth?: number) => this.ensureInputCursorVisible(contentWidth),
-        registerPaste: (content: string) => this.registerPaste(content),
-        executeBlockAction: (id: string) => this.executeBlockAction(id),
-        cyclePanelTab: (direction: 'next' | 'prev') => this.cyclePanelTab(direction),
-        onPanelInputConsumed: (activePanel: Panel | null, key: string) => this.handlePanelIntegrationAction(activePanel, key),
-        panelManager: this.uiServices.shell.panelManager,
-        keybindingsManager: this.uiServices.shell.keybindingsManager,
-        getWrappedPromptInfo: (contentWidth: number) => this.getWrappedPromptInfo(contentWidth),
-        moveCursorVertical: (direction: -1 | 1) => this.moveCursorVertical(direction),
-        handlePathCompletion: () => this.handlePathCompletion(),
-        handleBlockToggle: () => this.handleBlockToggle(),
-        findMarkerAtPos: (pos: number) => this.findMarkerAtPos(pos),
-        cleanupMarkerRegistry: (text: string) => this.cleanupMarkerRegistry(text),
-        expandPrompt: (text: string) => this.expandPrompt(text),
-        exitApp: this.exitApp,
-      };
+      const context = this.feedContext;
+      // Sync mutable scalars from handler into the reused context.
+      context.prompt = this.prompt;
+      context.cursorPos = this.cursorPos;
+      context.commandMode = this.commandMode;
+      context.panelFocused = this.panelFocused;
+      context.indicatorFocused = this.indicatorFocused;
+      context.helpOverlayActive = this.helpOverlayActive;
+      context.helpScrollOffset = this.helpScrollOffset;
+      context.shortcutsOverlayActive = this.shortcutsOverlayActive;
+      context.shortcutsScrollOffset = this.shortcutsScrollOffset;
+      context.selectionCallback = this.selectionCallback;
+      context.nextPasteId = this.nextPasteId;
+      context.nextImageId = this.nextImageId;
+      context.mouseDownRow = this.mouseDownRow;
+      context.mouseDownCol = this.mouseDownCol;
+      context.contentWidth = this.contentWidth;
+      // Sync semi-stable refs that may be wired after construction.
+      context.commandRegistry = this.commandRegistry;
+      context.commandContext = this.commandContext;
+      context.autocomplete = this.autocomplete;
+      context.inputHistory = this.inputHistory;
+      context.conversationManager = this.conversationManager;
+      // Swap requestRender to buffered version for this feed.
+      context.requestRender = bufferedRequestRender;
       this.syncFeedSelectionCallback = (callback) => {
         context.selectionCallback = callback;
       };

package/src/input/keybindings.ts

@@ -138,11 +138,14 @@ function resolveKeybindingsPath(options?: KeybindingsManagerOptions): string {
 export class KeybindingsManager {
   private bindings: Record<KeyAction, KeyCombo[]>;
   private configPath: string;
+  /** Inverted lookup map: composite key → KeyAction. Built in buildLookupMap(). */
+  private lookupMap = new Map<string, KeyAction>();
 
   constructor(options: KeybindingsManagerOptions) {
     this.configPath = resolveKeybindingsPath(options);
     // Start with deep copy of defaults
     this.bindings = this.cloneDefaults();
+    this.buildLookupMap();
   }
 
   private cloneDefaults(): Record<KeyAction, KeyCombo[]> {
@@ -184,6 +187,33 @@ export class KeybindingsManager {
     } catch (err) {
       logger.debug('keybindings: failed to load config file', { path: this.configPath, err: summarizeError(err) });
     }
+    this.buildLookupMap();
+  }
+
+  /**
+   * buildLookupMap — Rebuild the inverted lookup map from the current bindings table.
+   * Called after constructor init and after loadFromDisk().
+   * Map key format: "logicalName:ctrl:shift:alt" (booleans as 0/1).
+   * Last writer wins for duplicate combos (deterministic: iterate actions in order).
+   */
+  private buildLookupMap(): void {
+    this.lookupMap.clear();
+    for (const [action, combos] of Object.entries(this.bindings) as [KeyAction, KeyCombo[]][]) {
+      for (const combo of combos) {
+        const key = `${combo.key}:${combo.ctrl ? 1 : 0}:${combo.shift ? 1 : 0}:${combo.alt ? 1 : 0}`;
+        this.lookupMap.set(key, action);
+      }
+    }
+  }
+
+  /**
+   * lookup — O(1) keybinding lookup by token.
+   * Returns the matching KeyAction, or null if no binding matches.
+   */
+  lookup(token: { logicalName?: string; ctrl?: boolean; shift?: boolean; alt?: boolean }): KeyAction | null {
+    if (!token.logicalName) return null;
+    const key = `${token.logicalName}:${token.ctrl ? 1 : 0}:${token.shift ? 1 : 0}:${token.alt ? 1 : 0}`;
+    return this.lookupMap.get(key) ?? null;
   }
 
   private validateCombos(combos: unknown[]): combos is KeyCombo[] {