Keybinding System & Vim Emulation: 17 Contexts, 5 Result Types, State Machine

Problem

CLI tools must support many overlapping key functions (e.g., Enter for chat submit vs. confirmation, Ctrl+R for global history search, chord Ctrl+X Ctrl+K to stop agents, Vim d2w to delete two words). A single global keypress listener causes conflicts such as Ctrl+C exiting the program, the first chord key triggering unrelated actions, Vim . corrupting text, and missing platform‑specific fallbacks.

Context Isolation – 17 Compile‑Time UI Contexts

The engine enumerates 17 contexts in src/keybindings/contexts.ts. TypeScript forces exhaustive handling, so adding a new context produces a compile‑time error if not covered.

export const KEYBINDING_CONTEXTS = [
  'Global',
  'Chat',
  'Autocomplete',
  'Confirmation',
  'Help', 'Transcript', 'HistorySearch', 'Task',
  'ThemePicker', 'Settings', 'Tabs', 'Attachments',
  'Footer', 'MessageSelector', 'DiffDialog',
  'ModelPicker', 'Select', 'Plugin',
] as const;

// "last win" merge: user bindings appended after defaults
const mergedBindings = [...defaultBindings, ...userParsed];

const DEFAULT_BINDINGS = [
  {
    context: 'Chat',
    bindings: {
      'ctrl+x ctrl+k': 'chat:killAgents', // chord binding
      enter: 'chat:submit',
      escape: 'chat:cancel',
      // Platform fallback: Windows Ctrl+V is taken, downgrade to Alt+V
      [getPlatform() === 'windows' ? 'alt+v' : 'ctrl+v']: 'chat:imagePaste',
    },
  },
];

When multiple contexts are active (e.g., Chat + Global), the more specific context wins over Global. Users can explicitly unbind a key with null (e.g., "meta+p": null), which swallows the event instead of leaving it unbound.

Resolve Engine – Five Exhaustive Result Types

The resolver returns a discriminated union that forces handling of every branch at compile time.

export type ResolveResult =
  | { type: 'match'; action: string }
  | { type: 'none' }
  | { type: 'unbound' }
  | { type: 'chord_started'; pending: ParsedKeystroke[] }
  | { type: 'chord_cancelled' };

export type ChordResolveResult =
  | { type: 'match'; action: string }
  | { type: 'none' }
  | { type: 'unbound' }
  | { type: 'chord_started'; pending: ParsedKeystroke[] }
  | { type: 'chord_cancelled' };

function modifiersMatch(inkMods: InkModifiers, target: ParsedKeystroke): boolean {
  if (inkMods.ctrl !== target.ctrl) return false;
  if (inkMods.shift !== target.shift) return false;
  // "alt+k" and "meta+k" are equivalent in traditional terminals
  const targetNeedsMeta = target.alt || target.meta;
  if (inkMods.meta !== targetNeedsMeta) return false;
  // Super (Cmd/Win) only supported by Kitty protocol
  if (inkMods.super !== target.super) return false;
  return true;
}

Example execution path for the chord Ctrl+X Ctrl+K:

Press Ctrl+X → engine returns chord_started and stores pending state.

Press Ctrl+K → matches chat:killAgents, executes the action, and returns to idle.

If any other key (including Esc) is pressed while pending, the engine returns chord_cancelled.

The prefix Ctrl+X is chosen because it is idle in the chat UI (readline’s “cut to line start”), avoiding conflicts.

Vim State Machine – Parsing NORMAL Mode Commands

The Vim emulation tracks four states: idle, count, operator, and operatorCount. The flow for d2w is: d →

operator{d}

2

→

operatorCount{d, 2}

w

→ execute deleteWord with count = 2, then return to idle.

type VimCommandState =
  | { type: 'idle' }
  | { type: 'count'; count: number }
  | { type: 'operator'; op: string }
  | { type: 'operatorCount'; op: string; count: number };

function handleInput(key: string, mods: InkModifiers) {
  const state = stateRef.current;
  // ESC in INSERT mode switches to NORMAL and moves cursor left
  if (mods.escape && state.mode === 'INSERT') {
    if (offset > 0) setOffset(offset - 1);
    stateRef.current = { mode: 'NORMAL', command: { type: 'idle' }, insertedText: '' };
    setMode('NORMAL');
    return;
  }
  // INSERT mode passes through text and records it for dot‑repeat
  if (state.mode === 'INSERT') {
    if (!mods.backspace) {
      stateRef.current = { ...state, insertedText: state.insertedText + key };
    }
    baseInput.onInput(key, mods);
    return;
  }
  // NORMAL mode: map arrow keys to hjkl, then feed to state machine
  const mappedKey = mods.leftArrow ? 'h' : mods.rightArrow ? 'l' :
                    mods.upArrow ? 'k' : mods.downArrow ? 'j' : key;
  const result = processNormalCommand(state.command, mappedKey, buildContext(cursor));
  if (result.execute) result.execute();
  stateRef.current = {
    mode: 'NORMAL',
    command: result.next ?? (result.execute ? { type: 'idle' } : state.command),
    insertedText: '',
  };
}

Dot‑Repeat Details

Dot‑repeat re‑executes the last recorded change. The implementation sets isRepeat=true so that recordChange is skipped, preventing the repeat operation itself from becoming the new lastChange and causing an infinite self‑reference loop.

type Change =
  | { type: 'insert'; text: string }
  | { type: 'x'; count: number }
  | { type: 'operator'; op: string; motion: string; count: number };

function dotRepeat() {
  const lastChange = stateRef.current.lastChange;
  if (!lastChange) return;
  const cursor = Cursor.fromText(props.value, props.columns, offset);
  // isRepeat=true skips recordChange!
  const ctx = buildContext(cursor, /* isRepeat */ true);
  switch (lastChange.type) {
    case 'insert':
      if (lastChange.text) {
        const newCursor = cursor.insert(lastChange.text);
        props.onChange(newCursor.text);
        setOffset(newCursor.offset);
      }
      break;
    case 'operator':
      executeOperator(lastChange.op, lastChange.motion, lastChange.count, ctx);
      break;
    // other change types omitted for brevity
  }
}

Because isRepeat=true bypasses recordChange, lastChange always refers to the user‑initiated action, not a previous dot‑repeat.

Two Hook Layers – yK vs b_

yK

receives the resolved action name and runs business logic (e.g., submit, cancel). b_ receives the raw Ink keypress, allowing the Vim state machine to interpret low‑level keys. Keeping these paths separate prevents spaghetti code.

// High‑level business hook (post‑resolution)
yK({
  'chat:submit': () => handleSubmit(),
  'chat:cancel': () => handleCancel(),
  'confirm:cycleMode': () => cycleToNextConfirmOption(),
}, { context: 'Chat' });

// Low‑level raw keypress hook
b_((key, mods, event) => {
  if (isVimMode()) {
    handleVimInput(key, mods);
    // Prevent NORMAL‑mode keys from reaching the input box
    event.stopImmediatePropagation();
    return;
  }
}, { isActive: !isDisabled });

Typical architectural mistake: mixing INSERT text handling and NORMAL command parsing in a single if/else block. Correct approach: route all NORMAL keys through the state machine; only INSERT keys are passed through to the text input.

Reusing the Engine in Your Project

A minimal implementation that includes only context isolation and the five result types solves about 80 % of common cases with roughly 20 % of the code.

type Context = 'Chat' | 'Confirmation' | 'Global'; // extend as needed

type ResolveResult =
  | { type: 'match'; action: string }
  | { type: 'none' }
  | { type: 'unbound' };

const bindings: Record<Context, Record<string, string | null>> = {
  Chat: { enter: 'chat:submit', escape: 'chat:cancel' },
  Confirmation: { enter: 'confirm:accept', escape: 'confirm:reject' },
  Global: { 'ctrl+c': 'app:interrupt', 'ctrl+r': 'history:search' },
};

function resolveKey(key: string, activeContexts: Context[]): ResolveResult {
  // Specific contexts win over Global
  for (const ctx of [...activeContexts.filter(c => c !== 'Global'), 'Global'] as Context[]) {
    const action = bindings[ctx]?.[key];
    if (action !== undefined) {
      return action === null ? { type: 'unbound' } : { type: 'match', action };
    }
  }
  return { type: 'none' };
}

If Vim mode is required, call event.stopImmediatePropagation() for any key that must not reach the input box while in NORMAL mode.

Conclusion

The keybinding system demonstrates that terminal CLI key handling should be built as a stateful parsing engine rather than a flat switch‑case. Compile‑time enumeration of 17 contexts turns runtime conflicts into compile‑time errors. The five‑variant ResolveResult union guarantees exhaustive handling of matches, no‑matches, explicit unbindings, chord starts, and chord cancellations. The Vim state machine’s isRepeat=true flag prevents dot‑repeat self‑reference loops. Separating high‑level business hooks ( yK) from low‑level raw event hooks ( b_) keeps the architecture clean and extensible.