website

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) {

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.

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 {

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`).