- OpenTUI Keymap là key/command engine host-agnostic đầu tiên kết nối bindings trực tiếp với command registry thành một adaptive dispatch model.
- Engine luôn biết key nào active, reachable, shadowed hay pending - bất kể plugin nào đã chỉnh sửa mapping.
- Ra đời từ nhu cầu thực tế của OpenCode, AI coding agent đang chạy production cùng OpenTUI v0.2.3 với 10.8k GitHub stars.
- Addons compose với engine - which-key overlay, vim-like bindings, custom key syntax - không work around nó.
TL;DR
OpenTUI Keymap là một host-agnostic key/command engine cho DOM-like apps - giải quyết vấn đề mà hầu hết keymap library bỏ qua: kết nối binding với command registry thành một mô hình dispatch thống nhất. Engine luôn biết key nào đang active, reachable, shadowed, hay pending - bất kể plugin nào đã chỉnh sửa mapping. Sinh ra từ nhu cầu thực tế của OpenCode, AI coding agent chạy trong terminal được backed bởi SST.
Vấn đề cần giải quyết
Hầu hết keymap library hiện tại - tinykeys, hotkeys-js, Mousetrap - dừng lại ở tầng binding: map key combo sang callback. Sau đó, app phải tự xây command layer riêng bên trên. Kết quả là hai thứ tách rời nhau:
- Bindings không biết command nào chúng đang trigger
- Command registry không biết key nào đang gọi nó
- Không có nguồn sự thật duy nhất về trạng thái keymap tại bất kỳ thời điểm nào
Khi @kmdrfx tìm kiếm giải pháp cho OpenCode - cần plugin có thể hoàn toàn kiểm soát key mapping và command behavior - không có library nào đáp ứng. Vì vậy, OpenTUI Keymap ra đời. Tác giả tự nhận đây là "extremely over-engineered" - và nói điều đó với giọng tự hào hoàn toàn có lý.
Cơ chế hoạt động
OpenTUI Keymap xây dựng trên mô hình adaptive dispatch: nhiều layer binding và command compose lại thành một engine duy nhất có thể query theo thời gian thực.
- Hosts cung cấp: focus, hierarchy, input events, lifecycle. Engine không phụ thuộc vào host cụ thể - từ DOM browser đến terminal đều dùng được cùng một core
- Addons mở rộng: parsing, tokens, sequence patterns, command metadata, resolvers, interceptors, event matching - tất cả đều composable
- Layers stack lên nhau: plugin nào cũng có thể thêm hoặc override mà không phá vỡ layer bên dưới
Điểm mấu chốt là engine luôn duy trì live state đầy đủ. Bất cứ lúc nào cũng có thể query: key nào active, reachable, shadowed, pending, hay dispatchable. Help view, command palette, debug UI - tất cả đều query thẳng vào engine thay vì phải rebuild knowledge riêng.
Tính năng nổi bật
| Tính năng | Mô tả |
|---|---|
| Which-key plugin | Overlay hiển thị key reachable từ live state - không cần rebuild riêng |
| Vim-like bindings | Leader key, sequence patterns, modal-style theo kiểu declarative |
| Command palettes | Query engine trực tiếp cho help view, palette, graph/debug UI |
| Custom key syntax | Plugin có thể định nghĩa config syntax riêng cho key strokes |
| Composable addons | Addons compose với keymap, không work around nó |
| Graph visualization | Debug UI hiển thị toàn bộ layers -> bindings -> commands theo thời gian thực |
Ảnh demo phía trên cho thấy Graph View của OpenTUI Keymap: bên trái là layers (Prompt, Log, Draft, Notes, Beta, Alpha, Global, Commands), giữa là bindings (space, tab, ctrl+d, escape, g g...), bên phải là command targets. Leader state, pending path, và active view được hiển thị live ở góc phải màn hình.
So với các giải pháp hiện tại
Hầu hết keymap library chỉ giải quyết một nửa bài toán:
- tinykeys / hotkeys-js / Mousetrap: binding-only, không có command layer, không có live state query
- which-key.nvim: đọc bindings có sẵn của Neovim để hiển thị popup - không phải engine độc lập, không portable ra ngoài Neovim
- Vim native keymaps: layering tốt nhưng editor-specific, không generalize cho DOM-like apps hay terminal app tùy ý
OpenTUI Keymap là giải pháp đầu tiên unify cả hai phía: bindings + commands trong một adaptive model, với discoverability build sẵn từ live state - không cần app tự rebuild lại kiến thức đó.
Khi nào nên dùng
OpenTUI Keymap phù hợp nhất khi:
- Bạn đang xây keyboard-first terminal app với OpenTUI và muốn vim-like UX
- App cần plugin ecosystem mà các plugin có thể extend keymap độc lập và composable
- Cần help overlay / command palette phản ánh đúng trạng thái keymap thực tế tại thời điểm đó
- Muốn vim-like bindings hay leader key theo kiểu declarative, không hardcode logic dispatch
- Hoặc đơn giản là bạn thích hệ thống "extremely over-engineered" và không thấy đó là vấn đề
Tiếp theo
OpenTUI Keymap được announce cùng thời điểm OpenTUI v0.2.3 (6/5/2026) - 10.8k GitHub stars, 68 releases, Zig core với TypeScript bindings. OpenTUI hiện đang powers OpenCode trong production và sắp tới là terminal.shop (SST). Demo đầy đủ có trong replies của tweet gốc @kmdrfx. Theo dõi @kmdrfx và repo anomalyco/opentui để cập nhật addons và release tiếp theo.
Nguồn: @kmdrfx trên X, opentui.com, opencode.ai/docs/keybinds.