diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index c710821..6fa8f2c 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -197,3 +197,6 @@ tags: [daily] - 12:56 (<1min) | `memory-compiler` - **Asked:** File a new WezTerm keyboard concepts article into the wiki knowledge base. - **Done:** Created `dotfiles/wezterm-keyboard-concepts.md` with internal wikilinks and updated master index. +- 12:57 (<1min) | `memory-compiler` + - **Asked:** Compile a new article about WezTerm keyboard encoding into the wiki knowledge base. + - **Done:** Filed structured article covering 4 encoding schemes with priority order table under wiki/dotfiles topic. diff --git a/raw/Keyboard Encoding - Wez's Terminal Emulator.md b/raw/_processed/Keyboard Encoding - Wez's Terminal Emulator.md similarity index 100% rename from raw/Keyboard Encoding - Wez's Terminal Emulator.md rename to raw/_processed/Keyboard Encoding - Wez's Terminal Emulator.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 2710c64..c1e17dd 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -28,7 +28,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/qa/_index\|qa/]] | Filed answers to queries (saved with `--file-back`) | 0 | | [[wiki/homelab/_index\|homelab/]] | Self-hosted infra: Proxmox install, IOMMU/PCI passthrough, hypervisor setup, budget builds | 2 | | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 | -| [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 13 | +| [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 14 | | [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 14 | | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 | diff --git a/wiki/dotfiles/_index.md b/wiki/dotfiles/_index.md index a1a2fde..2b5bc5f 100644 --- a/wiki/dotfiles/_index.md +++ b/wiki/dotfiles/_index.md @@ -17,3 +17,4 @@ Linux terminal customization, shell configs, CLI tool setups, and ricing guides. | [[wiki/dotfiles/wezterm-key-bindings\|wezterm-key-bindings]] | Key binding config: modifiers, phys/mapped/raw prefixes, Leader key, CapsLock-as-leader, debug | wezterm.org/config/keys.html | 2026-04-17 | | [[wiki/dotfiles/wezterm-key-tables\|wezterm-key-tables]] | Modal keybinding layers via key_tables: ActivateKeyTable, activation stack, one_shot, timeout | wezterm.org/config/key-tables.html | 2026-04-17 | | [[wiki/dotfiles/wezterm-keyboard-concepts\|wezterm-keyboard-concepts]] | OS input concepts (IME, dead keys, AltGr, physical vs mapped keys) and how WezTerm processes them | wezterm.org/config/keyboard-concepts.html | 2026-04-17 | +| [[wiki/dotfiles/wezterm-keyboard-encoding\|wezterm-keyboard-encoding]] | xterm, modifyOtherKeys, CSI-u, Kitty protocol, Win32 Input Mode — priority order and config options | wezterm.org/config/key-encoding.html | 2026-04-17 | diff --git a/wiki/dotfiles/wezterm-keyboard-encoding.md b/wiki/dotfiles/wezterm-keyboard-encoding.md new file mode 100644 index 0000000..9004ee7 --- /dev/null +++ b/wiki/dotfiles/wezterm-keyboard-encoding.md @@ -0,0 +1,76 @@ +--- +title: "WezTerm Keyboard Encoding" +aliases: [wezterm-key-encoding, terminal-keyboard-encoding] +tags: [wezterm, terminal, keyboard, encoding, kitty-protocol, xterm] +sources: [raw/Keyboard Encoding - Wez's Terminal Emulator.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +## Overview + +When a keypress doesn't match a key assignment, WezTerm encodes it into a byte stream sent to the PTY. Four encoding schemes are supported, with a priority order that determines which wins. + +## Encoding Schemes + +### 1. Default — xterm Compatible +- Generates events for key **presses only** (not releases) +- Covers the key set from 1980s terminal hardware +- Main limitation: ambiguity with Control modifier — e.g. `Ctrl-I` = ASCII Tab, indistinguishable from Tab itself + +### 2. xterm modifyOtherKeys +- Triggered by escape sequence `CSI >4;Nm` (N = 0, 1, or 2) +- Encodes certain modified keys unambiguously so apps can tell `Ctrl-I` from Tab +- Spec: [modifyOtherKeys](https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys) +- Available since WezTerm `20221119-145034-49b9839f` +- Overridden by `enable_csi_u_key_encoding` and `allow_win32_input_mode` + +### 3. CSI-u / fixterms / libtickit +- Config: `enable_csi_u_key_encoding = true` +- Attempts to resolve xterm ambiguity and expose more modifiers +- **Not recommended** — breaks some keys in backwards-incompatible ways; apps cannot detect or request it +- Overridden by `allow_win32_input_mode` + +### 4. Kitty Keyboard Protocol +- Config: `enable_kitty_keyboard = true` +- Most capable: apps can request varying levels of enhancement +- Adds support for `CMD` / `Super` / `Windows` modifier keys +- Apps opt-in via escape sequences; WezTerm honors those requests when enabled +- Spec: [Kitty comprehensive keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) + +### 5. Win32 Input Mode (Windows only) +- Config: `allow_win32_input_mode` — defaults to `true` on Windows +- Enables key **release** events and distinguishes left/right modifier keys +- Best compatibility with win32 console apps (e.g. Far Manager) +- Highest priority — overrides both CSI-u and modifyOtherKeys + +## Priority Order + +``` +Win32 Input Mode > CSI-u > Kitty Protocol > modifyOtherKeys > xterm default +``` + +> `allow_win32_input_mode` wins everything on Windows. `enable_csi_u_key_encoding` beats modifyOtherKeys. + +## Config Options Reference + +| Option | Type | Default | Effect | +|--------|------|---------|--------| +| `enable_kitty_keyboard` | bool | false | Honor app requests for kitty protocol | +| `enable_csi_u_key_encoding` | bool | false | Enable CSI-u/fixterms encoding (not recommended) | +| `allow_win32_input_mode` | bool | true (Win) | Enable Win32 Input Mode on Windows | + +## Key Takeaways + +- WezTerm defaults to **xterm-compatible** encoding — works everywhere but has modifier ambiguity +- **Kitty Keyboard Protocol** is the modern, recommended enhancement — apps opt in via escape sequences +- **CSI-u** (`enable_csi_u_key_encoding`) is available but not recommended due to backwards-compatibility breakage +- On **Windows**, `allow_win32_input_mode = true` by default and takes highest priority +- Encoding scheme choice matters for Neovim, Emacs, and other apps that rely on distinguishing modified keys + +## Related + +- [[wiki/dotfiles/wezterm-key-bindings|WezTerm Key Bindings]] — how to configure key assignments in Lua +- [[wiki/dotfiles/wezterm-key-tables|WezTerm Key Tables]] — modal keybinding layers +- [[wiki/dotfiles/wezterm-keyboard-concepts|WezTerm Keyboard Concepts]] — OS-level input concepts (IME, dead keys, AltGr) +- [[wiki/dotfiles/wezterm-default-keybindings|WezTerm Default Keybindings]] — full default key assignment table