Track DECSET/DECRST 1007 (Alternate Scroll Mode)

Private mode 1007 is xterm's Alternate Scroll Mode, which corresponds to its
alternateScroll resource: while the alternate screen is active and the
application has not enabled mouse tracking, the terminal translates wheel
input into cursor up/down keys, so full-screen programs that do not read the
mouse (less, vim without mouse=a) still respond to scrolling.

SwiftTerm currently drops 1007 into the "Unhandled DEC Private Mode" branch,
so an embedder that implements this translation has no way to let an
application turn it off, and DECRQM cannot answer a query about it.

This only tracks the state and exposes it as Terminal.alternateScrollMode;
translating wheel events stays with the host view, as with the other mouse
state SwiftTerm tracks. The mode is wired into DECSET, DECRST, DECRQM and
RIS, matching how 1004 is handled.

One deliberate choice worth a second opinion: the default here is true,
matching Ghostty (src/terminal/modes.zig marks mouse_alternate_scroll
default true), while xterm's own alternateScroll resource defaults to false.
True keeps the wheel working out of the box in less/vim, which is what
users on macOS terminals tend to expect, but I am happy to flip it to false
to match xterm if you would rather follow the reference implementation.

Author: jizhi0v0

Sources/SwiftTerm/Terminal.swift

@@ -476,6 +476,16 @@ open class Terminal {
     /// Indicates that the application has toggled bracketed paste mode, which means that when content is pasted into
     /// the terminal, the content will be wrapped in "ESC [ 200 ~" to start, and "ESC [ 201 ~" to end.
     public private(set) var bracketedPasteMode: Bool = false
+
+    /// Tracks DECSET/DECRST private mode 1007 (Alternate Scroll Mode, xterm's "alternateScroll" resource).
+    /// When true and the alternate screen buffer is active without an application mouse-tracking mode enabled,
+    /// hosts are expected to translate scroll wheel input into cursor up/down key sequences instead of scrolling,
+    /// so that full-screen apps that do not read the mouse (e.g. `less`, `vim` without `mouse=a`) still respond
+    /// to the scroll wheel. SwiftTerm only tracks the mode's state here; translating wheel events is left to the
+    /// host view, which can read this property to decide how to route them.
+    /// xterm's own default for this resource is false; we default to true here to match modern terminals
+    /// (e.g. Ghostty) that enable it out of the box.
+    public private(set) var alternateScrollMode: Bool = true
 
     private var charset: [UInt8:String]? = nil
     private var gCharsets: [[UInt8:String]?] = [CharSets.defaultCharset, nil, nil, nil]
@@ -954,6 +964,7 @@ open class Terminal {
         setInsertMode(false)
         setWraparound(true)
         bracketedPasteMode = false
+        alternateScrollMode = true
 
         keyboardModeNormal = KeyboardModeState()
         keyboardModeAlt = KeyboardModeState()
@@ -4428,6 +4439,8 @@ open class Terminal {
                 res = mouseProtocol == .utf8 ? modeSet : modeReset
             case 1006:
                 res = mouseProtocol == .sgr ? modeSet : modeReset
+            case 1007:
+                res = alternateScrollMode ? modeSet : modeReset
             case 1015:
                 res = mouseProtocol == .urxvt ? modeSet : modeReset
             case 1016:
@@ -5257,6 +5270,8 @@ open class Terminal {
                 mouseMode = .off
             case 1004: // send focusin/focusout events
                 sendFocus = false
+            case 1007: // alternate scroll mode (xterm's alternateScroll resource)
+                alternateScrollMode = false
             case 2500: // box drawing mirroring off
                 updateCurrentBidiState(property: .boxMirroring) { $0.boxMirroring = false }
             case 2501: // autodetect off: use the SPD-selected direction
@@ -5356,6 +5371,8 @@ open class Terminal {
     //     Ps = 1 0 0 3  -> Use All Motion Mouse Tracking.
     //     Ps = 1 0 0 4  -> Send FocusIn/FocusOut events.
     //     Ps = 1 0 0 5  -> Enable Extended Mouse Mode.
+    //     Ps = 1 0 0 7  -> Enable Alternate Scroll Mode, xterm.  This
+    //     corresponds to the alternateScroll resource.
     //     Ps = 1 0 1 0  -> Scroll to bottom on tty output (rxvt).
     //     Ps = 1 0 1 1  -> Scroll to bottom on key press (rxvt).
     //     Ps = 1 0 3 4  -> Interpret "meta" key, sets eighth bit.
@@ -5506,6 +5523,8 @@ open class Terminal {
                 // the application does not assume it is unfocused until the
                 // first real focus change.
                 sendFocusReport()
+            case 1007: // alternate scroll mode (xterm's alternateScroll resource)
+                alternateScrollMode = true
             case 2500: // box drawing mirroring (terminal-wg)
                 updateCurrentBidiState(property: .boxMirroring) { $0.boxMirroring = true }
             case 2501: // autodetect paragraph direction (terminal-wg)

Tests/SwiftTermTests/AlternateScrollModeTests.swift

@@ -0,0 +1,78 @@
+//
+//  AlternateScrollModeTests.swift
+//
+//  DECSET/DECRST 1007: Alternate Scroll Mode (xterm's "alternateScroll" resource).
+//  SwiftTerm only tracks the mode's boolean state on Terminal.alternateScrollMode;
+//  translating scroll wheel events into cursor keys while the alt screen is active
+//  is the host view's responsibility.
+//
+import Foundation
+import Testing
+
+@testable import SwiftTerm
+
+final class AlternateScrollModeTests: TerminalDelegate {
+    var sent: [UInt8] = []
+
+    func send(source: Terminal, data: ArraySlice<UInt8>) {
+        sent.append(contentsOf: data)
+    }
+
+    func makeTerminal() -> Terminal {
+        Terminal(delegate: self, options: TerminalOptions(cols: 80, rows: 25))
+    }
+
+    @Test func defaultsToEnabled() {
+        let terminal = makeTerminal()
+        #expect(terminal.alternateScrollMode == true, "SwiftTerm defaults 1007 to on, matching modern terminals like Ghostty")
+    }
+
+    @Test func decsetEnablesAndDecrstDisables() {
+        let terminal = makeTerminal()
+
+        terminal.feed(text: "\u{1b}[?1007l")
+        #expect(terminal.alternateScrollMode == false)
+
+        terminal.feed(text: "\u{1b}[?1007h")
+        #expect(terminal.alternateScrollMode == true)
+
+        terminal.feed(text: "\u{1b}[?1007l")
+        #expect(terminal.alternateScrollMode == false)
+    }
+
+    @Test func fullResetRestoresDefault() {
+        let terminal = makeTerminal()
+        terminal.feed(text: "\u{1b}[?1007l")
+        #expect(terminal.alternateScrollMode == false)
+
+        // RIS (Reset to Initial State) should restore the mode to its default (on).
+        terminal.feed(text: "\u{1b}c")
+        #expect(terminal.alternateScrollMode == true)
+    }
+
+    @Test func modeIsIndependentOfAltScreenAndMouseTracking() {
+        let terminal = makeTerminal()
+        terminal.feed(text: "\u{1b}[?1007l")
+        terminal.feed(text: "\u{1b}[?1049h") // enter alt screen
+        #expect(terminal.alternateScrollMode == false, "entering the alt screen must not change 1007's own state")
+
+        terminal.feed(text: "\u{1b}[?1000h") // vt200 mouse tracking
+        #expect(terminal.alternateScrollMode == false, "enabling mouse tracking must not implicitly change 1007's state")
+    }
+
+    /// DECRQM (`CSI ? 1007 $ p`) must report the mode, the way the neighbouring
+    /// mouse modes (1000-1006) already do — otherwise an application can set the
+    /// mode but never find out what it currently is.
+    @Test func decrqmReportsCurrentState() {
+        let terminal = makeTerminal()
+
+        sent = []
+        terminal.feed(text: "\u{1b}[?1007$p")
+        #expect(String(decoding: sent, as: UTF8.self) == "\u{1b}[?1007;1$y", "set is reported as 1")
+
+        terminal.feed(text: "\u{1b}[?1007l")
+        sent = []
+        terminal.feed(text: "\u{1b}[?1007$p")
+        #expect(String(decoding: sent, as: UTF8.self) == "\u{1b}[?1007;2$y", "reset is reported as 2")
+    }
+}