From f94f32be798d8cc8dc5a6f6780dee75112d775cd Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Wed, 11 Oct 2023 22:01:37 -0700
Subject: [PATCH] website

---
 src/Surface.zig                       |  6 +++-
 src/terminal/Terminal.zig             |  2 +-
 src/termio/Exec.zig                   |  2 +-
 website/app/vt/xtshiftescape/page.mdx | 41 +++++++++++++++++++++++++++
 4 files changed, 48 insertions(+), 3 deletions(-)
 create mode 100644 website/app/vt/xtshiftescape/page.mdx

diff --git a/src/Surface.zig b/src/Surface.zig
index f01e49b96..c3fd1e9d4 100644
--- a/src/Surface.zig
+++ b/src/Surface.zig
@@ -1519,7 +1519,11 @@ fn mouseShiftCapture(self: *const Surface, lock: bool) bool {
 
     // If thet terminal explicitly requests it then we always allow it
     // since we processed never/always at this point.
-    if (self.io.terminal.flags.mouse_shift_capture) return true;
+    switch (self.io.terminal.flags.mouse_shift_capture) {
+        .false => return false,
+        .true => return true,
+        .null => {},
+    }
 
     // Otherwise, go with the user's preference
     return switch (self.config.mouse_shift_capture) {
diff --git a/src/terminal/Terminal.zig b/src/terminal/Terminal.zig
index caea93437..687bb4a91 100644
--- a/src/terminal/Terminal.zig
+++ b/src/terminal/Terminal.zig
@@ -106,7 +106,7 @@ flags: packed struct {
     /// Set via the XTSHIFTESCAPE sequence. If true (XTSHIFTESCAPE = 1)
     /// then we want to capture the shift key for the mouse protocol
     /// if the configuration allows it.
-    mouse_shift_capture: bool = false,
+    mouse_shift_capture: enum { null, false, true } = .null,
 } = .{},
 
 /// The event types that can be reported for mouse-related activities.
diff --git a/src/termio/Exec.zig b/src/termio/Exec.zig
index 85bb0d49c..bdf9bffad 100644
--- a/src/termio/Exec.zig
+++ b/src/termio/Exec.zig
@@ -1522,7 +1522,7 @@ const StreamHandler = struct {
     }
 
     pub fn setMouseShiftCapture(self: *StreamHandler, v: bool) !void {
-        self.terminal.flags.mouse_shift_capture = v;
+        self.terminal.flags.mouse_shift_capture = if (v) .true else .false;
     }
 
     pub fn setAttribute(self: *StreamHandler, attr: terminal.Attribute) !void {
diff --git a/website/app/vt/xtshiftescape/page.mdx b/website/app/vt/xtshiftescape/page.mdx
new file mode 100644
index 000000000..093442689
--- /dev/null
+++ b/website/app/vt/xtshiftescape/page.mdx
@@ -0,0 +1,41 @@
+import VTSequence from "@/components/VTSequence";
+
+# Set Shift-Escape (XTSHIFTESCAPE)
+
+<VTSequence sequence={["CSI", ">", "Pn", "s"]} />
+
+Configure whether mouse reports are allowed to capture the `shift` modifier.
+
+The parameter `n` must be an integer equal to 0 or 1. If `n` is omitted,
+`n` defaults to 1. If `n` is an invalid value, this sequence does nothing.
+
+When a terminal program requests [mouse reporting](#TODO), some mouse
+reporting modes also report the modifier keys that are pressed (control, shift,
+etc.). This would disable the ability for a terminal user to natively select
+text if they typically select text using left-click and drag, since the
+left-click event is captured by the running program.
+
+To get around this limitation, many terminal emulators (including xterm)
+use the `shift` modifier to disable mouse reporting temporarily, allowing
+native text selection to work. In this scenario, however, the running
+terminal program cannot detect shift-clicks because the terminal emulator
+captures the event.
+
+This sequence (`XTSHIFTESCAPE`) allows configuring this behavior. If
+`n` is `0`, the terminal is allowed to override the shift key and not pass
+it through to the terminal program. If `n` is `1`, the terminal program
+is requesting that the shift modifier is sent using standard mouse
+reporting formats.
+
+In either case, the terminal emulator is not forced to respect this request.
+For example, `xterm` has a `never` and `always` terminal configuration
+to never allow terminal programs to capture shift or to always allow them,
+respectively. If either of these configurations are set, `XTSHIFTESCAPE`
+has zero effect.
+
+`xterm` also has `false` and `true` terminal configurations. In the `false`
+scenario, the terminal emulator will override `shift` (not allow the terminal
+program to see it) _unless it is explicitly requested_ via `XTSHIFTESCAPE`.
+The `true` scenario is the exact opposite: pass the shift modifier through
+to the running terminal program unless the terminal program explicitly states
+it doesn't need to know about it (`n = 0`).