fix: keep escape-prefixed terminal key bindings intact (#4759)

* fix: keep escape-prefixed terminal key bindings intact

refs #4751

* test: cover escape-prefixed option+backspace binding

refs #4751

(cherry picked from commit 898f733f92dbbe53c428845534b03adb573f92be)

1 files changed, 250 insertions, 28 deletions

diff --git a/src/client/input.rs b/src/client/input.rs
index ab46e788..08254155 100644
--- a/src/client/input.rs
+++ b/src/client/input.rs
@@ -143,8 +143,7 @@ fn unix_stdin_reader_loop(
                 return;
             }
             if held_escape
-                && stdin_read_ready(&reader, crate::raw_input::RAW_INPUT_IDLE_FLUSH_TIMEOUT_MS)
-                    == Some(false)
+                && stdin_read_ready(&reader, framer.held_input_flush_timeout_ms()) == Some(false)
                 && !send_unix_input_chunks(
                     framer.flush_timeout(),
                     &event_tx,
@@ -253,10 +252,8 @@ fn unix_stdin_reader_loop(
                         return;
                     }
                     if held_escape
-                        && stdin_read_ready(
-                            &reader,
-                            crate::raw_input::RAW_INPUT_IDLE_FLUSH_TIMEOUT_MS,
-                        ) == Some(false)
+                        && stdin_read_ready(&reader, framer.held_input_flush_timeout_ms())
+                            == Some(false)
                     {
                         let chunks = framer.flush_timeout();
                         if !framer.has_pending_input() {
@@ -379,14 +376,14 @@ fn idle_flush_timeout_ms(
     framer: &crate::raw_input::RawInputByteFramer,
     host_mouse_capture_active: bool,
 ) -> i32 {
-    // A mouse report split after ESC[ is still ambiguous with legacy Alt+[.
-    // Give it the mouse-active grace period without changing timeout decoding.
-    if host_mouse_capture_active
-        && (framer.has_pending_lone_escape()
-            || framer.has_pending_csi_introducer()
-            || framer.has_pending_incomplete_mouse_sequence())
-    {
+    if !host_mouse_capture_active {
+        return crate::raw_input::RAW_INPUT_IDLE_FLUSH_TIMEOUT_MS;
+    }
+    if framer.has_pending_lone_escape() || framer.has_pending_incomplete_mouse_sequence() {
         crate::raw_input::MOUSE_ACTIVE_ESCAPE_SEQUENCE_FLUSH_TIMEOUT_MS
+    } else if framer.has_pending_csi_introducer() {
+        // A mouse report split after ESC[ is still ambiguous with legacy Alt+[.
+        crate::raw_input::MOUSE_ACTIVE_CSI_INTRODUCER_FLUSH_TIMEOUT_MS
     } else {
         crate::raw_input::RAW_INPUT_IDLE_FLUSH_TIMEOUT_MS
     }
@@ -799,19 +796,16 @@ mod tests {
         assert_eq!(framer.flush_timeout().len(), 1);
     }
 
-    #[test]
-    fn captured_mouse_report_split_after_csi_survives_idle_gap() {
-        let mut framer = crate::raw_input::RawInputByteFramer::for_host_input();
-        framer.enable_host_appearance_query_on_focus();
-        assert_eq!(framer.push(b"\x1b[I"), vec![b"\x1b[I".to_vec()]);
-        assert!(framer.push(b"\x1b[").is_empty());
-
-        // #4630 input.bin offsets 10465/10467: ESC[ and its continuation
-        // arrived 32.937 ms apart. Apply the Unix reader's two idle waits
-        // without sleeping, using its production timeout selector.
-        let gap = std::time::Duration::from_micros(32_937);
+    /// Applies the Unix reader's idle waits for a gap between two host writes
+    /// without sleeping, using its production timeout selector.
+    fn reader_chunks_across_gap(
+        framer: &mut crate::raw_input::RawInputByteFramer,
+        mouse_capture: bool,
+        gap: std::time::Duration,
+        next: &[u8],
+    ) -> Vec<Vec<u8>> {
         let first_wait =
-            std::time::Duration::from_millis(idle_flush_timeout_ms(&framer, true) as u64);
+            std::time::Duration::from_millis(idle_flush_timeout_ms(framer, mouse_capture) as u64);
         let mut chunks = Vec::new();
         if gap >= first_wait {
             chunks.extend(framer.flush_timeout());
@@ -819,13 +813,237 @@ mod tests {
                 && gap
                     >= first_wait
                         + std::time::Duration::from_millis(
-                            crate::raw_input::RAW_INPUT_IDLE_FLUSH_TIMEOUT_MS as u64,
+                            framer.held_input_flush_timeout_ms() as u64
                         )
             {
                 chunks.extend(framer.flush_timeout());
             }
         }
-        chunks.extend(framer.push(b"<35;64;37M\x1b[<35;65;36M\x1b[<35;64;36M"));
+        chunks.extend(framer.push(next));
+        chunks
+    }
+
+    fn confirmed_disambiguation_framer() -> crate::raw_input::RawInputByteFramer {
+        let mut framer = crate::raw_input::RawInputByteFramer::for_host_input();
+        framer.set_host_escape_disambiguation_active(true);
+        framer
+    }
+
+    #[test]
+    fn confirmed_disambiguation_keeps_mouse_report_split_by_delayed_tail() {
+        // #3480: the tail of a click arrived 350 ms after its ESC.
+        let gap = std::time::Duration::from_millis(350);
+        for (prefix, tail) in [
+            (b"\x1b".as_slice(), b"[<0;5;5M".as_slice()),
+            (b"\x1b[", b"<0;5;5M"),
+            (b"\x1b[<0;", b"5;5M"),
+        ] {
+            let mut framer = confirmed_disambiguation_framer();
+            assert!(framer.push(prefix).is_empty());
+
+            assert_eq!(
+                reader_chunks_across_gap(&mut framer, true, gap, tail),
+                vec![b"\x1b[<0;5;5M".to_vec()],
+                "prefix {prefix:?} must rejoin its mouse tail"
+            );
+        }
+    }
+
+    #[test]
+    fn confirmed_disambiguation_keeps_escape_prefixed_bindings_intact() {
+        // Ghostty's macOS Alt+Left/Right and Alacritty Shift+Enter bindings (#4751).
+        // iTerm2's Natural Text Editing preset also sends ESC DEL for Option+Backspace.
+        for binding in [b"\x1bb".as_slice(), b"\x1bf", b"\x1b\r", b"\x1b\x7f"] {
+            let mut framer = confirmed_disambiguation_framer();
+
+            assert_eq!(framer.push(binding), vec![binding.to_vec()]);
+        }
+    }
+
+    #[test]
+    fn confirmed_disambiguation_releases_escape_prefixed_bindings_after_bounded_wait() {
+        // Terminal text bindings can send ESC, Alt+[ or Alt+O alone (#4751).
+        let gap = std::time::Duration::from_secs(1);
+        for binding in [b"\x1b".as_slice(), b"\x1b[", b"\x1bO"] {
+            let mut framer = confirmed_disambiguation_framer();
+            assert!(framer.push(binding).is_empty());
+
+            assert_eq!(
+                reader_chunks_across_gap(&mut framer, true, gap, b"x"),
+                vec![binding.to_vec(), b"x".to_vec()],
+                "binding {binding:?} must not be held or dropped"
+            );
+        }
+    }
+
+    #[test]
+    fn confirmed_disambiguation_separates_escape_prefixed_binding_from_fast_next_key() {
+        // Typing right after an Alt+O / Alt+[ / ESC text binding must not glue
+        // the next key onto it while Herdr is watching for a delayed mouse tail.
+        for (binding, next, gap_ms) in [
+            (b"\x1bO".as_slice(), b"q".as_slice(), 80),
+            (b"\x1b[", b"A", 80),
+            (b"\x1b", b"x", 200),
+        ] {
+            let mut framer = confirmed_disambiguation_framer();
+            assert!(framer.push(binding).is_empty());
+
+            assert_eq!(
+                reader_chunks_across_gap(
+                    &mut framer,
+                    true,
+                    std::time::Duration::from_millis(gap_ms),
+                    next
+                ),
+                vec![binding.to_vec(), next.to_vec()],
+                "binding {binding:?} followed by {next:?} after {gap_ms} ms"
+            );
+        }
+    }
+
+    #[test]
+    fn confirmed_disambiguation_releases_binding_while_host_reply_is_pending() {
+        for (binding, next) in [(b"\x1b[".as_slice(), b"A".as_slice()), (b"\x1b", b"x")] {
+            let mut framer = confirmed_disambiguation_framer();
+            framer.host_cell_size_query_sent();
+            framer.host_color_query_sent();
+            assert!(framer.push(binding).is_empty());
+
+            assert_eq!(
+                reader_chunks_across_gap(
+                    &mut framer,
+                    true,
+                    std::time::Duration::from_secs(1),
+                    next
+                ),
+                vec![binding.to_vec(), next.to_vec()],
+                "binding {binding:?} must not stay held behind a pending host reply"
+            );
+        }
+    }
+
+    #[test]
+    fn confirmed_disambiguation_keeps_slow_host_reply_and_paste_whole() {
+        let paste = b"200~hello\n\x1b[201~";
+        for (tail, gap_ms) in [(b"6;21;10t".as_slice(), 55), (paste.as_slice(), 80)] {
+            let mut framer = confirmed_disambiguation_framer();
+            framer.host_cell_size_query_sent();
+            assert!(framer.push(b"\x1b[").is_empty());
+
+            let mut whole = b"\x1b[".to_vec();
+            whole.extend_from_slice(tail);
+            assert_eq!(
+                reader_chunks_across_gap(
+                    &mut framer,
+                    true,
+                    std::time::Duration::from_millis(gap_ms),
+                    tail
+                ),
+                vec![whole],
+                "tail {tail:?} after {gap_ms} ms must stay attached to ESC["
+            );
+        }
+    }
+
+    #[test]
+    fn confirmed_disambiguation_keeps_osc_reply_split_after_escape_whole() {
+        let mut framer = confirmed_disambiguation_framer();
+        framer.host_color_query_sent();
+        assert!(framer.push(b"\x1b").is_empty());
+
+        let tail = b"]11;rgb:1111/2222/3333\x07";
+        let mut whole = b"\x1b".to_vec();
+        whole.extend_from_slice(tail);
+        assert_eq!(
+            reader_chunks_across_gap(
+                &mut framer,
+                true,
+                std::time::Duration::from_millis(155),
+                tail
+            ),
+            vec![whole]
+        );
+    }
+
+    #[test]
+    fn confirmed_disambiguation_mouse_wait_does_not_consume_later_reply_hold() {
+        let mut framer = confirmed_disambiguation_framer();
+        framer.enable_host_appearance_query_on_focus();
+        assert_eq!(framer.push(b"\x1b[I"), vec![b"\x1b[I".to_vec()]);
+        assert!(framer.push(b"\x1b[<0;").is_empty());
+
+        assert!(reader_chunks_across_gap(
+            &mut framer,
+            true,
+            std::time::Duration::from_millis(650),
+            b"\x1b[?997;"
+        )
+        .is_empty());
+        assert_eq!(
+            reader_chunks_across_gap(
+                &mut framer,
+                true,
+                std::time::Duration::from_millis(15),
+                b"2n"
+            ),
+            vec![b"\x1b[?997;2n".to_vec()]
+        );
+    }
+
+    #[test]
+    fn confirmed_disambiguation_keeps_kitty_escape_immediate() {
+        let mut framer = confirmed_disambiguation_framer();
+
+        assert_eq!(framer.push(b"\x1b[27u"), vec![b"\x1b[27u".to_vec()]);
+    }
+
+    #[test]
+    fn confirmed_disambiguation_joins_escape_binding_split_before_wait_ends() {
+        let mut framer = confirmed_disambiguation_framer();
+        assert!(framer.push(b"\x1b").is_empty());
+
+        assert_eq!(
+            reader_chunks_across_gap(
+                &mut framer,
+                true,
+                std::time::Duration::from_millis(40),
+                b"\r"
+            ),
+            vec![b"\x1b\r".to_vec()]
+        );
+    }
+
+    #[test]
+    fn legacy_alt_bracket_is_not_glued_to_following_key() {
+        let mut framer = crate::raw_input::RawInputByteFramer::for_host_input();
+        assert!(framer.push(b"\x1b[").is_empty());
+
+        assert_eq!(
+            reader_chunks_across_gap(
+                &mut framer,
+                true,
+                std::time::Duration::from_millis(80),
+                b"a"
+            ),
+            vec![b"\x1b[".to_vec(), b"a".to_vec()]
+        );
+    }
+
+    #[test]
+    fn captured_mouse_report_split_after_csi_survives_idle_gap() {
+        let mut framer = crate::raw_input::RawInputByteFramer::for_host_input();
+        framer.enable_host_appearance_query_on_focus();
+        assert_eq!(framer.push(b"\x1b[I"), vec![b"\x1b[I".to_vec()]);
+        assert!(framer.push(b"\x1b[").is_empty());
+
+        // #4630 input.bin offsets 10465/10467: ESC[ and its continuation
+        // arrived 32.937 ms apart.
+        let chunks = reader_chunks_across_gap(
+            &mut framer,
+            true,
+            std::time::Duration::from_micros(32_937),
+            b"<35;64;37M\x1b[<35;65;36M\x1b[<35;64;36M",
+        );
         assert_eq!(
             chunks,
             vec![
@@ -858,13 +1076,17 @@ mod tests {
                 crate::raw_input::RAW_INPUT_IDLE_FLUSH_TIMEOUT_MS
             );
         }
-        for framer in [&escape, &csi, &sgr_mouse, &default_mouse] {
+        for framer in [&escape, &sgr_mouse, &default_mouse] {
             assert_eq!(
                 idle_flush_timeout_ms(framer, true),
                 crate::raw_input::MOUSE_ACTIVE_ESCAPE_SEQUENCE_FLUSH_TIMEOUT_MS
             );
         }
         assert_eq!(
+            idle_flush_timeout_ms(&csi, true),
+            crate::raw_input::MOUSE_ACTIVE_CSI_INTRODUCER_FLUSH_TIMEOUT_MS
+        );
+        assert_eq!(
             idle_flush_timeout_ms(&unrelated, true),
             crate::raw_input::RAW_INPUT_IDLE_FLUSH_TIMEOUT_MS
         );