Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

mux: report the remote pane's keyboard encoding so kitty keys work over the mux

RoversX06f50d884a2d
diff --git a/Cargo.lock b/Cargo.lock
index 079558f8..c130c404 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -868,6 +868,7 @@ dependencies = [
"thinkterm-proto",
"thiserror 1.0.69",
"varbincode",
+ "wezterm-input-types 0.1.0",
"wezterm-term",
"zstd",
]
diff --git a/codec/Cargo.toml b/codec/Cargo.toml
index 6895851b..db9938ca 100644
--- a/codec/Cargo.toml
+++ b/codec/Cargo.toml
@@ -17,6 +17,7 @@ thinkterm-proto.workspace = true
serde = {workspace=true, features = ["rc", "derive"]}
futures-lite.workspace = true
termwiz.workspace = true
+wezterm-input-types.workspace = true
thiserror.workspace = true
varbincode.workspace = true
wezterm-term = { workspace=true, features=["use_serde"] }
diff --git a/codec/src/lib.rs b/codec/src/lib.rs
index 132ed833..4251a5ab 100644
--- a/codec/src/lib.rs
+++ b/codec/src/lib.rs
@@ -31,6 +31,8 @@ use std::path::PathBuf;
use std::sync::Arc;
use termwiz::hyperlink::Hyperlink;
use termwiz::image::{ImageData, TextureCoordinate};
+use termwiz::input::KeyboardEncoding;
+use wezterm_input_types::KittyKeyboardFlags;
use termwiz::surface::{Line, SequenceNo};
use thiserror::Error;
use wezterm_term::color::ColorPalette;
@@ -1360,6 +1362,10 @@ pub struct GetPaneRenderChangesResponse {
/// to know that a wheel notch has no scrollback to travel through and
/// belongs to the full-screen program instead.
pub alt_screen: bool,
+ /// How the program in the pane wants keys encoded. Without it a client
+ /// treats every remote pane as plain xterm and never speaks the kitty
+ /// keyboard protocol, or win32-input-mode, to a program that asked.
+ pub keyboard_encoding: WireKeyboardEncoding,
pub cursor_position: StableCursorPosition,
pub dimensions: RenderableDimensions,
pub dirty_lines: Vec<Range<StableRowIndex>>,
@@ -1373,6 +1379,44 @@ pub struct GetPaneRenderChangesResponse {
pub seqno: SequenceNo,
}
+/// `termwiz::input::KeyboardEncoding` for the wire: the termwiz type has no
+/// serde, and the kitty flags travel as their bits.
+#[derive(Deserialize, Serialize, PartialEq, Eq, Debug, Clone, Copy, Default)]
+pub enum WireKeyboardEncoding {
+ #[default]
+ Xterm,
+ CsiU,
+ Win32,
+ Kitty(u16),
+}
+
+impl From<KeyboardEncoding> for WireKeyboardEncoding {
+ fn from(encoding: KeyboardEncoding) -> Self {
+ match encoding {
+ KeyboardEncoding::Xterm => Self::Xterm,
+ KeyboardEncoding::CsiU => Self::CsiU,
+ KeyboardEncoding::Win32 => Self::Win32,
+ KeyboardEncoding::Kitty(flags) => Self::Kitty(flags.bits()),
+ }
+ }
+}
+
+impl From<WireKeyboardEncoding> for KeyboardEncoding {
+ fn from(encoding: WireKeyboardEncoding) -> Self {
+ match encoding {
+ WireKeyboardEncoding::Xterm => Self::Xterm,
+ WireKeyboardEncoding::CsiU => Self::CsiU,
+ WireKeyboardEncoding::Win32 => Self::Win32,
+ // Bits this build does not know are dropped rather than refused:
+ // a newer program's extra flag must not turn the whole protocol
+ // off.
+ WireKeyboardEncoding::Kitty(bits) => {
+ Self::Kitty(KittyKeyboardFlags::from_bits_truncate(bits))
+ }
+ }
+ }
+}
+
#[derive(Deserialize, Serialize, PartialEq, Debug)]
pub struct GetLines {
pub pane_id: PaneId,
@@ -1739,6 +1783,7 @@ mod golden {
pane_id: 1,
mouse_grabbed: false,
alt_screen: true,
+ keyboard_encoding: WireKeyboardEncoding::Kitty(3),
cursor_position: StableCursorPosition::default(),
dimensions: RenderableDimensions {
cols: 80,
@@ -1780,9 +1825,11 @@ mod golden {
1, 4, 104, 111, 115, 116, 4, 117, 115, 101, 114, 100, 2, 3, 0, 128, 226, 207, 170, 6, 1, 7,
100, 101, 102, 97, 117, 108, 116, 128, 226, 207, 170, 6, 1, 4,
];
+ // Re-captured for codec 64, when `keyboard_encoding` (the `3, 3`
+ // after `alt_screen`: variant Kitty, flag bits 3) joined the response.
const RENDER_CHANGES: &[u8] = &[
- 1, 0, 1, 0, 0, 0, 1, 80, 24, 100, 121, 180, 127, 96, 128, 5, 128, 3, 0, 2, 0, 2, 5, 6, 5,
- 116, 105, 116, 108, 101, 0, 0, 0, 0, 0, 42,
+ 1, 0, 1, 3, 3, 0, 0, 0, 1, 80, 24, 100, 121, 180, 127, 96, 128, 5, 128, 3, 0, 2, 0, 2, 5,
+ 6, 5, 116, 105, 116, 108, 101, 0, 0, 0, 0, 0, 42,
];
const LAYOUT_JSON: &str = r#"["Empty",{"Split":{"left":{"Leaf":{"window_id":1,"tab_id":2,"pane_id":3,"title":"left","size":{"rows":24,"cols":80,"pixel_width":640,"pixel_height":384,"dpi":96},"working_dir":"file:///tmp/x","is_active_pane":true,"is_zoomed_pane":false,"alt_screen":true,"workspace":"default","cursor_pos":{"x":0,"y":0,"shape":"Default","visibility":"Visible"},"physical_top":-3,"top_row":0,"left_col":0,"tty_name":"/dev/ttys001"}},"right":{"Stack":{"active":0,"panes":[{"window_id":1,"tab_id":2,"pane_id":4,"title":"stacked","size":{"rows":24,"cols":80,"pixel_width":640,"pixel_height":384,"dpi":96},"working_dir":"file:///tmp/x","is_active_pane":true,"is_zoomed_pane":false,"alt_screen":true,"workspace":"default","cursor_pos":{"x":0,"y":0,"shape":"Default","visibility":"Visible"},"physical_top":-3,"top_row":0,"left_col":0,"tty_name":"/dev/ttys001"}],"pane_stack_id":7}},"node":{"direction":"Horizontal","first":{"rows":24,"cols":40,"pixel_width":320,"pixel_height":384,"dpi":96},"second":{"rows":24,"cols":39,"pixel_width":312,"pixel_height":384,"dpi":96}}}}]"#;
@@ -2471,3 +2518,34 @@ mod test {
);
}
}
+
+#[cfg(test)]
+mod keyboard_encoding_tests {
+ use super::*;
+
+ #[test]
+ fn the_keyboard_encoding_survives_the_wire_both_ways() {
+ for encoding in [
+ KeyboardEncoding::Xterm,
+ KeyboardEncoding::CsiU,
+ KeyboardEncoding::Win32,
+ KeyboardEncoding::Kitty(
+ KittyKeyboardFlags::DISAMBIGUATE_ESCAPE_CODES
+ | KittyKeyboardFlags::REPORT_EVENT_TYPES,
+ ),
+ ] {
+ let wire: WireKeyboardEncoding = encoding.into();
+ let back: KeyboardEncoding = wire.into();
+ assert_eq!(back, encoding);
+ }
+ }
+
+ #[test]
+ fn unknown_kitty_bits_are_dropped_not_fatal() {
+ let back: KeyboardEncoding = WireKeyboardEncoding::Kitty(0x8000 | 1).into();
+ assert_eq!(
+ back,
+ KeyboardEncoding::Kitty(KittyKeyboardFlags::DISAMBIGUATE_ESCAPE_CODES)
+ );
+ }
+}
diff --git a/wezterm-client/src/pane/clientpane.rs b/wezterm-client/src/pane/clientpane.rs
index c50c01e8..65632700 100644
--- a/wezterm-client/src/pane/clientpane.rs
+++ b/wezterm-client/src/pane/clientpane.rs
@@ -25,7 +25,7 @@ use std::collections::{BTreeMap, HashMap};
use std::ops::Range;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
-use termwiz::input::KeyEvent;
+use termwiz::input::{KeyEvent, KeyboardEncoding};
use termwiz::surface::SequenceNo;
use url::Url;
use wezterm_dynamic::Value;
@@ -241,6 +241,10 @@ pub struct ClientPane {
clipboard: Mutex<Option<Arc<dyn Clipboard>>>,
mouse_grabbed: Mutex<bool>,
alt_screen: Mutex<bool>,
+ /// As last reported by the server. The GUI's key encoders consult it
+ /// before every key: a pane left at Xterm never gets kitty-protocol or
+ /// win32-input-mode bytes, whatever the remote program asked for.
+ keyboard_encoding: Mutex<KeyboardEncoding>,
requested_size: Mutex<Option<TerminalSize>>,
ignore_next_kill: Mutex<bool>,
user_vars: Mutex<HashMap<String, String>>,
@@ -364,6 +368,7 @@ impl ClientPane {
client: Arc::clone(client),
remote_pane_id,
remote_tab_id: Arc::clone(&remote_tab_id),
+ queue: Default::default(),
};
let mouse = Arc::new(Mutex::new(MouseState::new(
@@ -431,6 +436,7 @@ impl ClientPane {
clipboard: Mutex::new(None),
mouse_grabbed: Mutex::new(false),
alt_screen: Mutex::new(alt_screen),
+ keyboard_encoding: Mutex::new(KeyboardEncoding::Xterm),
requested_size: Mutex::new(Some(size)),
ignore_next_kill: Mutex::new(false),
unseen_output: Mutex::new(false),
@@ -450,6 +456,7 @@ impl ClientPane {
Pdu::GetPaneRenderChangesResponse(mut delta) => {
*self.mouse_grabbed.lock() = delta.mouse_grabbed;
*self.alt_screen.lock() = delta.alt_screen;
+ *self.keyboard_encoding.lock() = delta.keyboard_encoding.into();
let bonus_lines = std::mem::take(&mut delta.bonus_lines);
let client = { Arc::clone(&self.renderable.lock().inner.borrow().client) };
@@ -1154,7 +1161,11 @@ impl Pane for ClientPane {
}
fn key_up(&self, _key: KeyCode, _mods: KeyModifiers) -> anyhow::Result<()> {
- // TODO: decide how to handle key_up for mux client
+ // Nothing to send, and that matches a local pane: the xterm-style
+ // encoders emit no bytes for a release. The protocols that do
+ // report releases (kitty, win32-input-mode) are encoded by the GUI
+ // and written through `writer()`, once `get_keyboard_encoding`
+ // tells it the remote program asked for them.
Ok(())
}
@@ -1245,6 +1256,10 @@ impl Pane for ClientPane {
*self.alt_screen.lock()
}
+ fn get_keyboard_encoding(&self) -> KeyboardEncoding {
+ *self.keyboard_encoding.lock()
+ }
+
fn get_current_working_dir(&self, _policy: CachePolicy) -> Option<Url> {
self.renderable.lock().inner.borrow().working_dir.clone()
}
@@ -1374,28 +1389,84 @@ struct PaneWriter {
client: Arc<ClientInner>,
remote_pane_id: TabId,
remote_tab_id: Arc<AtomicUsize>,
+ queue: Arc<Mutex<WriteQueue>>,
}
-impl std::io::Write for PaneWriter {
- fn write(&mut self, data: &[u8]) -> Result<usize, std::io::Error> {
- if self.client.remote_tab_input_is_blocked() {
- return Ok(data.len());
+/// Bytes written to a remote pane and not yet on the wire.
+///
+/// `Write::write` used to block its caller, the GUI thread, for a round
+/// trip per call; with the kitty keyboard protocol that is every
+/// keystroke. Writes queue here instead, and one task at a time drains
+/// the queue in order, sending whatever has piled up as a single
+/// WriteToPane.
+#[derive(Default)]
+struct WriteQueue {
+ pending: Vec<u8>,
+ draining: bool,
+}
+
+impl WriteQueue {
+ /// Queue `data`; true when the caller has to start the drain.
+ fn push(&mut self, data: &[u8]) -> bool {
+ self.pending.extend_from_slice(data);
+ !std::mem::replace(&mut self.draining, true)
+ }
+
+ /// Everything queued so far, or None once the drain is over.
+ fn take(&mut self) -> Option<Vec<u8>> {
+ if self.pending.is_empty() {
+ self.draining = false;
+ None
+ } else {
+ Some(std::mem::take(&mut self.pending))
}
- let remote_tab_id = self.remote_tab_id.load(Ordering::Relaxed);
- let payload = data.to_vec();
- promise::spawn::block_on(async {
- if self.client.prepare_remote_tab_input(remote_tab_id).await? {
- self.client
+ }
+}
+
+async fn drain_pane_writes(
+ client: Arc<ClientInner>,
+ remote_pane_id: TabId,
+ remote_tab_id: Arc<AtomicUsize>,
+ queue: Arc<Mutex<WriteQueue>>,
+) {
+ loop {
+ let Some(data) = queue.lock().take() else {
+ return;
+ };
+ let remote_tab_id = remote_tab_id.load(Ordering::Relaxed);
+ let sent = async {
+ if client.prepare_remote_tab_input(remote_tab_id).await? {
+ client
.client
.write_to_pane(WriteToPane {
- pane_id: self.remote_pane_id,
- data: payload,
+ pane_id: remote_pane_id,
+ data,
})
.await?;
}
Ok::<(), anyhow::Error>(())
- })
- .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, format!("{}", e)))?;
+ }
+ .await;
+ if let Err(err) = sent {
+ log::error!("writing to remote pane {remote_pane_id}: {err:#}");
+ }
+ }
+}
+
+impl std::io::Write for PaneWriter {
+ fn write(&mut self, data: &[u8]) -> Result<usize, std::io::Error> {
+ if self.client.remote_tab_input_is_blocked() {
+ return Ok(data.len());
+ }
+ if self.queue.lock().push(data) {
+ promise::spawn::spawn_into_main_thread(drain_pane_writes(
+ Arc::clone(&self.client),
+ self.remote_pane_id,
+ Arc::clone(&self.remote_tab_id),
+ Arc::clone(&self.queue),
+ ))
+ .detach();
+ }
Ok(data.len())
}
@@ -1746,4 +1817,21 @@ mod palette_delivery_tests {
assert!(!transition.palette_changed);
assert!(transition.provenance_changed);
}
+
+ #[test]
+ fn the_first_write_starts_the_drain_and_later_ones_ride_along() {
+ let mut queue = super::WriteQueue::default();
+ assert!(queue.push(b"a"), "nothing draining: start one");
+ assert!(
+ !queue.push(b"b"),
+ "a drain is running: it will pick this up"
+ );
+ assert_eq!(
+ queue.take().as_deref(),
+ Some(&b"ab"[..]),
+ "coalesced, in order"
+ );
+ assert!(queue.take().is_none(), "empty: the drain ends");
+ assert!(queue.push(b"c"), "and the next write starts a new one");
+ }
}
diff --git a/wezterm-mux-server-impl/src/sessionhandler.rs b/wezterm-mux-server-impl/src/sessionhandler.rs
index c2c95810..3025a007 100644
--- a/wezterm-mux-server-impl/src/sessionhandler.rs
+++ b/wezterm-mux-server-impl/src/sessionhandler.rs
@@ -71,6 +71,7 @@ pub(crate) struct PerPane {
dimensions: RenderableDimensions,
mouse_grabbed: bool,
alt_screen: bool,
+ keyboard_encoding: WireKeyboardEncoding,
/// Outer None means that this connection has never received application
/// palette state for the pane. Inner None is an explicit reset to the
/// client's own configured palette.
@@ -107,6 +108,11 @@ impl PerPane {
changed = true;
}
+ let keyboard_encoding: WireKeyboardEncoding = pane.get_keyboard_encoding().into();
+ if keyboard_encoding != self.keyboard_encoding {
+ changed = true;
+ }
+
let dims = pane.get_dimensions();
if dims != self.dimensions {
changed = true;
@@ -174,6 +180,7 @@ impl PerPane {
self.dimensions = dims;
self.mouse_grabbed = mouse_grabbed;
self.alt_screen = alt_screen;
+ self.keyboard_encoding = keyboard_encoding;
self.sent_images.remember(&bonus_lines);
let bonus_lines = bonus_lines.into();
@@ -181,6 +188,7 @@ impl PerPane {
pane_id: pane.pane_id(),
mouse_grabbed,
alt_screen,
+ keyboard_encoding,
dirty_lines: all_dirty_lines.iter().cloned().collect(),
dimensions: dims,
cursor_position,