feat: Terminal UX Improvements with Keybinding Hints and ESC Support

[m1ngsama]

Summary

Improve terminal user experience by adding keybinding hints, ESC key infrastructure, and better documentation alignment with standard Linux/Unix terminal conventions.

Enhancements

Keybinding Hints

• Add visible navigation hints to main menu: Navigation: j/k or ↑/↓ | Jump: g/G | Quit: q or Ctrl+C
• Self-documenting interface following vim, less, man page conventions
• Helps new users discover keyboard shortcuts

ESC Key Infrastructure

• Add ESC key recognition in vim-keys.ts
• Foundation for future back navigation and operation cancellation
• Properly captures and forwards escape sequences

Code Documentation

• Improve comments in vim-keys.ts explaining key mapping logic
• Better explanation of stdin event interception
• Clarify relationship between vim keys and native key codes

Symbol Standardization

• Consistent use of ASCII navigation symbols across all menus
• Align with Unix/Linux terminal operation patterns

Technical Details

vim-keys.ts changes:

// Added ESC key support
if (key.name === 'escape') {
  return originalEmit('keypress', null, { name: 'escape', sequence: '\x1b' });
}

menu.ts changes:

• Added keybinding hint line before main menu prompt
• Standardized navigation symbols

Benefits

• Discoverability: Users can see available keybindings without reading docs
• Standard Conventions: Follows patterns from vim, less, man pages
• Future-Ready: ESC infrastructure enables cancellation features
• Better Documentation: Code comments explain why, not just what

Files Changed

• src/core/vim-keys.ts: Add ESC support and improve documentation
• src/core/menu.ts: Add keybinding hints and standardize symbols

Testing Instructions

1. Run pnpm run dev
2. Verify keybinding hints display above main menu
3. Test all vim keybindings (j/k/g/G/q)
4. Test ESC key (infrastructure added, full functionality future work)
5. Verify symbols are consistent across menus

Future Enhancements

• Implement ESC-based back navigation in submenus
• Add operation cancellation during network requests
• Context-aware 'q' behavior (back vs quit)