feat: add #{pane_last_special_key} format variable (#315)

psmux · quazardous · psmux · commit aca11203e6dd · 2026-05-28T00:37:49.000+05:30
Add two read-only per-pane format variables for the last non-text key received on the interactive input route: - #{pane_last_special_key} -- canonical bind-key name (Escape, Enter, Up, F9, C-c, M-a, ...) - #{pane_last_special_key_ms} -- milliseconds since it arrived Complement of #{pane_last_text_input} (#311): together they partition all interactive keys into text vs non-text. Same route contract: set only in forward_key_to_active (the injected route never updates it). Also refactors the sync-input-aware pane selection into a shared for_each_receiving_pane helper, deduplicating the text-input stamping. Includes unit tests (key classification + naming) and E2E test. Co-authored-by: David Berlioz <berliozdavid@gmail.com>
diff --git a/docs/integration.md b/docs/integration.md
@@ -337,6 +337,34 @@ typing arrives on the interactive route. Consumers own all policy (e.g. treat
 "value < N ms" as "active"); psmux just exposes the timestamp, kept on the pane
 (no file, freed with the pane).
 
+### Special-key route signal (`#{pane_last_special_key}`)
+
+The sibling of `#{pane_last_text_input}` for **non-text** keys. Two read-only
+format variables describing the last key, other than printable text, that
+reached this pane via the interactive input route:
+
+- `#{pane_last_special_key}` -- its canonical bind-key name (`Escape`, `Enter`,
+  `Tab`, `Up`, `F9`, `C-c`, `M-a`, ...), empty until the first one.
+- `#{pane_last_special_key_ms}` -- milliseconds since it arrived, empty if none.
+
+```powershell
+psmux display-message -t dev -p '#{pane_last_special_key} #{pane_last_special_key_ms}'
+# e.g. "Escape 320", or " " if none yet
+```
+
+Same route contract as `#{pane_last_text_input}`:
+
+- **Interactive route** (`handle_key -> forward_key_to_active`) **updates** it.
+- **Injected route** (`send-keys` / `send-paste` / `send-text`) does **not**.
+- **Scope:** every key that is *not* printable text input -- `Escape`, `Enter`,
+  `Tab`, `Backspace`, arrows/navigation, function keys, and any `Ctrl`/`Alt`
+  chord. Printable text goes to `#{pane_last_text_input}` instead; together the
+  two partition all interactive keys. Names come from the same renderer
+  `list-keys` uses.
+
+Consumers own all policy (e.g. "name is `Escape` and `_ms` < N"); psmux just
+exposes the last key + its age, kept on the pane (no file, freed with it).
+
 ## Named Paste Buffers
 
 psmux supports named paste buffers for structured inter-pane data exchange:
diff --git a/src/format.rs b/src/format.rs
@@ -1146,6 +1146,24 @@ pub fn expand_var(var: &str, app: &AppState, win_idx: usize) -> String {
                 None => String::new(),
             }
         }
+        // The last NON-text key received on the INTERACTIVE input route
+        // (handle_key), by canonical bind-key name (Escape, Enter, Up, F9,
+        // C-c, M-a, ...); companion _ms gives its age in ms. Empty if none yet.
+        // Like pane_last_text_input, the injected route (send-keys /
+        // send-paste / send-text) does NOT update it. A read-only route signal
+        // -- consumers own any policy on top.
+        "pane_last_special_key" => {
+            match target_pane().and_then(|p| p.last_special_key.as_ref()) {
+                Some((_, name)) => name.clone(),
+                None => String::new(),
+            }
+        }
+        "pane_last_special_key_ms" => {
+            match target_pane().and_then(|p| p.last_special_key.as_ref()) {
+                Some((t, _)) => t.elapsed().as_millis().to_string(),
+                None => String::new(),
+            }
+        }
         "pane_active" => if fmt_pane_is_active { "1".into() } else { "0".into() },
         "pane_current_command" => {
             if let Some(p) = target_pane() {
diff --git a/src/input.rs b/src/input.rs
@@ -1883,32 +1883,45 @@ pub(crate) fn is_text_input_key(key: &KeyEvent) -> bool {
     )
 }
 
+/// Apply `f` to every pane that will RECEIVE the current interactive key --
+/// every non-dead pane under sync-input, else the active pane if alive -- so the
+/// route-signal timestamps match what's actually routed.
+fn for_each_receiving_pane<F: FnMut(&mut Pane)>(app: &mut AppState, mut f: F) {
+    let sync = app.sync_input;
+    let win = &mut app.windows[app.active_idx];
+    if sync {
+        fn walk<F: FnMut(&mut Pane)>(node: &mut Node, f: &mut F) {
+            match node {
+                Node::Leaf(p) if !p.dead => f(p),
+                Node::Leaf(_) => {}
+                Node::Split { children, .. } => { for c in children { walk(c, f); } }
+            }
+        }
+        walk(&mut win.root, &mut f);
+    } else if let Some(p) = active_pane_mut(&mut win.root, &win.active_path) {
+        if !p.dead {
+            f(p);
+        }
+    }
+}
+
 pub fn forward_key_to_active(app: &mut AppState, key: KeyEvent) -> io::Result<()> {
-    // Record use of the INTERACTIVE text-input route, exposed read-only as
-    // `#{pane_last_text_input}`. This route is handle_key -> forward_key_to_active;
-    // the injected route (send-keys / send-paste / send-text -> send_text_to_active)
-    // does NOT pass here, so it never updates the signal. Printable text only
-    // (no control / Ctrl / Alt). Stamp exactly the panes that will RECEIVE the
-    // key — every non-dead pane under sync-input, else the active pane if alive
-    // — so the timestamp matches what's actually routed.
+    // Record use of the INTERACTIVE input route as read-only route signals:
+    // `#{pane_last_text_input}` (printable text) and, for every other key,
+    // `#{pane_last_special_key}` / `_ms` (the last non-text key -- Esc, Enter,
+    // arrows, function keys, Ctrl/Alt chords -- by canonical bind-key name).
+    // This route is handle_key -> forward_key_to_active; the injected route
+    // (send-keys / send-paste / send-text -> send_text_to_active) does NOT pass
+    // here, so it never updates these signals. for_each_receiving_pane stamps
+    // exactly the panes that will RECEIVE the key, so the timestamps match what
+    // is actually routed.
     if is_text_input_key(&key) {
         let now = Instant::now();
-        let sync = app.sync_input;
-        let win = &mut app.windows[app.active_idx];
-        if sync {
-            fn mark(node: &mut Node, now: Instant) {
-                match node {
-                    Node::Leaf(p) if !p.dead => p.last_text_input = Some(now),
-                    Node::Leaf(_) => {}
-                    Node::Split { children, .. } => { for c in children { mark(c, now); } }
-                }
-            }
-            mark(&mut win.root, now);
-        } else if let Some(p) = active_pane_mut(&mut win.root, &win.active_path) {
-            if !p.dead {
-                p.last_text_input = Some(now);
-            }
-        }
+        for_each_receiving_pane(app, |p| p.last_text_input = Some(now));
+    } else {
+        let now = Instant::now();
+        let name = crate::config::format_key_binding(&(key.code, key.modifiers));
+        for_each_receiving_pane(app, |p| p.last_special_key = Some((now, name.clone())));
     }
 
     // On Windows, modified Enter delivery depends on the modifier:
@@ -3370,3 +3383,7 @@ mod tests_issue284_pageup_wsl;
 #[cfg(test)]
 #[path = "../tests-rs/test_pane_last_text_input.rs"]
 mod tests_pane_last_text_input;
+
+#[cfg(test)]
+#[path = "../tests-rs/test_pane_last_special_key.rs"]
+mod tests_pane_last_special_key;
diff --git a/src/pane.rs b/src/pane.rs
@@ -98,7 +98,7 @@ pub fn create_window(pty_system: &dyn portable_pty::PtySystem, app: &mut AppStat
         }
         let epoch = std::time::Instant::now() - Duration::from_secs(2);
         let configured_shell = if app.default_shell.is_empty() { None } else { Some(app.default_shell.as_str()) };
-        let pane = Pane { master: wp.master, writer: wp.writer, child: wp.child, term: wp.term, last_rows: rows, last_cols: cols, id: wp.pane_id, title: hostname_cached(), title_locked: false, child_pid: wp.child_pid, data_version: wp.data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape: wp.cursor_shape, bell_pending: wp.bell_pending, cpr_pending: wp.cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring: wp.output_ring };
+        let pane = Pane { master: wp.master, writer: wp.writer, child: wp.child, term: wp.term, last_rows: rows, last_cols: cols, id: wp.pane_id, title: hostname_cached(), title_locked: false, child_pid: wp.child_pid, data_version: wp.data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, last_special_key: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape: wp.cursor_shape, bell_pending: wp.bell_pending, cpr_pending: wp.cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring: wp.output_ring };
         let win_name = default_shell_name(None, configured_shell);
         let initial_pane_id = wp.pane_id;
         app.windows.push(Window { root: Node::Leaf(pane), active_path: vec![], name: win_name, id: app.next_win_id, activity_flag: false, bell_flag: false, silence_flag: false, last_output_time: std::time::Instant::now(), last_seen_version: 0, manual_rename: false, layout_index: 0, pane_mru: vec![initial_pane_id], zoom_saved: None, linked_from: None });
@@ -170,7 +170,7 @@ pub fn create_window(pty_system: &dyn portable_pty::PtySystem, app: &mut AppStat
     conpty_preemptive_dsr_response(&mut *pty_writer);
     let epoch = std::time::Instant::now() - Duration::from_secs(2);
     let pane_id = app.next_pane_id;
-    let pane = Pane { master: pair.master, writer: pty_writer, child, term, last_rows: size.rows, last_cols: size.cols, id: pane_id, title: hostname_cached(), title_locked: false, child_pid, data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape, bell_pending, cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring };
+    let pane = Pane { master: pair.master, writer: pty_writer, child, term, last_rows: size.rows, last_cols: size.cols, id: pane_id, title: hostname_cached(), title_locked: false, child_pid, data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, last_special_key: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape, bell_pending, cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring };
     app.next_pane_id += 1;
     let win_name = command.map(|c| default_shell_name(Some(c), None)).unwrap_or_else(|| default_shell_name(None, configured_shell));
     app.windows.push(Window { root: Node::Leaf(pane), active_path: vec![], name: win_name, id: app.next_win_id, activity_flag: false, bell_flag: false, silence_flag: false, last_output_time: std::time::Instant::now(), last_seen_version: 0, manual_rename: false, layout_index: 0, pane_mru: vec![pane_id], zoom_saved: None, linked_from: None });
@@ -286,7 +286,7 @@ pub fn create_window_raw(pty_system: &dyn portable_pty::PtySystem, app: &mut App
     conpty_preemptive_dsr_response(&mut *pty_writer);
     let epoch = std::time::Instant::now() - Duration::from_secs(2);
     let raw_pane_id = app.next_pane_id;
-    let pane = Pane { master: pair.master, writer: pty_writer, child, term, last_rows: size.rows, last_cols: size.cols, id: raw_pane_id, title: hostname_cached(), title_locked: false, child_pid, data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape, bell_pending, cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring };
+    let pane = Pane { master: pair.master, writer: pty_writer, child, term, last_rows: size.rows, last_cols: size.cols, id: raw_pane_id, title: hostname_cached(), title_locked: false, child_pid, data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, last_special_key: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape, bell_pending, cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring };
     app.next_pane_id += 1;
     let win_name = std::path::Path::new(&raw_args[0]).file_stem().and_then(|s| s.to_str()).unwrap_or(&raw_args[0]).to_string();
     app.windows.push(Window { root: Node::Leaf(pane), active_path: vec![], name: win_name, id: app.next_win_id, activity_flag: false, bell_flag: false, silence_flag: false, last_output_time: std::time::Instant::now(), last_seen_version: 0, manual_rename: false, layout_index: 0, pane_mru: vec![raw_pane_id], zoom_saved: None, linked_from: None });
@@ -389,7 +389,7 @@ pub fn split_active_with_command(app: &mut AppState, kind: LayoutKind, command:
         }
         let epoch = std::time::Instant::now() - Duration::from_secs(2);
         let new_pane_id = wp.pane_id;
-        let new_leaf = Node::Leaf(Pane { master: wp.master, writer: wp.writer, child: wp.child, term: wp.term, last_rows: rows, last_cols: cols, id: new_pane_id, title: hostname_cached(), title_locked: false, child_pid: wp.child_pid, data_version: wp.data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape: wp.cursor_shape, bell_pending: wp.bell_pending, cpr_pending: wp.cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring: wp.output_ring });
+        let new_leaf = Node::Leaf(Pane { master: wp.master, writer: wp.writer, child: wp.child, term: wp.term, last_rows: rows, last_cols: cols, id: new_pane_id, title: hostname_cached(), title_locked: false, child_pid: wp.child_pid, data_version: wp.data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, last_special_key: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape: wp.cursor_shape, bell_pending: wp.bell_pending, cpr_pending: wp.cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring: wp.output_ring });
         let win = &mut app.windows[app.active_idx];
         replace_leaf_with_split(&mut win.root, &win.active_path, kind, new_leaf);
         let mut new_path = win.active_path.clone();
@@ -442,7 +442,7 @@ pub fn split_active_with_command(app: &mut AppState, kind: LayoutKind, command:
     conpty_preemptive_dsr_response(&mut *pty_writer);
     let epoch = std::time::Instant::now() - Duration::from_secs(2);
     let split_pane_id = app.next_pane_id;
-    let new_leaf = Node::Leaf(Pane { master: pair.master, writer: pty_writer, child, term, last_rows: size.rows, last_cols: size.cols, id: split_pane_id, title: hostname_cached(), title_locked: false, child_pid, data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape, bell_pending, cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring });
+    let new_leaf = Node::Leaf(Pane { master: pair.master, writer: pty_writer, child, term, last_rows: size.rows, last_cols: size.cols, id: split_pane_id, title: hostname_cached(), title_locked: false, child_pid, data_version, last_title_check: epoch, last_infer_title: epoch, dead: false, last_text_input: None, last_special_key: None, vt_bridge_cache: None, vti_mode_cache: None, mouse_input_cache: None, cursor_shape, bell_pending, cpr_pending, copy_state: None, pane_style: None, squelch_until: None, output_ring });
     app.next_pane_id += 1;
     let win = &mut app.windows[app.active_idx];
     replace_leaf_with_split(&mut win.root, &win.active_path, kind, new_leaf);
diff --git a/src/popup.rs b/src/popup.rs
@@ -115,6 +115,7 @@ pub fn create_popup_pane(
         last_infer_title: epoch,
         dead: false,
         last_text_input: None,
+        last_special_key: None,
         vt_bridge_cache: None,
         vti_mode_cache: None,
         mouse_input_cache: None,
diff --git a/src/proxy_pane.rs b/src/proxy_pane.rs
@@ -264,6 +264,7 @@ pub fn create_proxy_pane(
         last_infer_title: epoch,
         dead: false,
         last_text_input: None,
+        last_special_key: None,
         vt_bridge_cache: None,
         vti_mode_cache: None,
         mouse_input_cache: None,
diff --git a/src/types.rs b/src/types.rs
@@ -113,6 +113,14 @@ pub struct Pane {
     /// `#{pane_last_text_input}` format variable. Lives on the pane, so it's
     /// freed with it (no separate lifecycle / file).
     pub last_text_input: Option<Instant>,
+    /// The last NON-text key routed via the INTERACTIVE input route
+    /// (`handle_key -> forward_key_to_active`): its canonical bind-key name
+    /// (`Escape`, `Enter`, `Up`, `F9`, `C-c`, `M-a`, ...) + the `Instant` it
+    /// arrived; `None` until the first one. Same route contract as
+    /// `last_text_input` (NOT updated by the injected route). The text vs
+    /// non-text split is `is_text_input_key`. Exposed read-only as
+    /// `#{pane_last_special_key}` / `#{pane_last_special_key_ms}`.
+    pub last_special_key: Option<(Instant, String)>,
     /// Cached VT bridge detection result (for mouse injection).
     /// Updated on first mouse event and refreshed every 2 seconds.
     pub vt_bridge_cache: Option<(Instant, bool)>,
diff --git a/tests-rs/test_pane_last_special_key.rs b/tests-rs/test_pane_last_special_key.rs
@@ -0,0 +1,51 @@
+// `#{pane_last_special_key}` / `_ms` -- the last NON-text key on the interactive
+// route, by canonical bind-key name. "Special" is the complement of
+// `is_text_input_key` (#311): everything that is not printable text input --
+// Escape, Enter, Tab, Backspace, arrows, function keys, and Ctrl/Alt chords.
+// The name comes from `format_key_binding`, the same renderer `list-keys` uses.
+//
+// The route separation itself is structural, not tested here: the injected
+// route (send-keys / send-paste / send-text) goes through send_text_to_active,
+// never forward_key_to_active, so it can't reach this signal.
+
+use crate::config::format_key_binding;
+use crate::input::is_text_input_key;
+use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+
+fn is_special(code: KeyCode, mods: KeyModifiers) -> bool {
+    !is_text_input_key(&KeyEvent::new(code, mods))
+}
+fn name(code: KeyCode, mods: KeyModifiers) -> String {
+    format_key_binding(&(code, mods))
+}
+
+#[test]
+fn special_keys_are_classified_and_named() {
+    // Each is non-text (so it routes to the special-key signal) and renders to
+    // its canonical bind-key name.
+    assert!(is_special(KeyCode::Esc, KeyModifiers::NONE));
+    assert_eq!(name(KeyCode::Esc, KeyModifiers::NONE), "Escape");
+
+    assert!(is_special(KeyCode::Enter, KeyModifiers::NONE));
+    assert_eq!(name(KeyCode::Enter, KeyModifiers::NONE), "Enter");
+
+    assert!(is_special(KeyCode::Char('c'), KeyModifiers::CONTROL));
+    assert_eq!(name(KeyCode::Char('c'), KeyModifiers::CONTROL), "C-c");
+
+    assert!(is_special(KeyCode::Char('a'), KeyModifiers::ALT));
+    assert_eq!(name(KeyCode::Char('a'), KeyModifiers::ALT), "M-a");
+
+    assert!(is_special(KeyCode::F(9), KeyModifiers::NONE));
+    assert_eq!(name(KeyCode::F(9), KeyModifiers::NONE), "F9");
+
+    assert!(is_special(KeyCode::Up, KeyModifiers::NONE));
+    assert_eq!(name(KeyCode::Up, KeyModifiers::NONE), "Up");
+}
+
+#[test]
+fn printable_text_is_not_special() {
+    // Plain text routes to #{pane_last_text_input}, never the special-key var.
+    assert!(!is_special(KeyCode::Char('a'), KeyModifiers::NONE));
+    assert!(!is_special(KeyCode::Char('Z'), KeyModifiers::SHIFT)); // capital
+    assert!(!is_special(KeyCode::Char(' '), KeyModifiers::NONE)); // space is text
+}
diff --git a/tests/test_pr315_pane_last_special_key.ps1 b/tests/test_pr315_pane_last_special_key.ps1
