Reorder SBQUERY Ps values and replace magic numbers with named constants

Drop Ps=0 (default alias) and reorder to Ps=1 (last command),
Ps=2 (last N commands), Ps=3 (in-progress) for a simpler specification.
Introduce SBQueryType struct with constexpr named constants to eliminate
magic number literals in the handler and tests. Replace raw escape
sequences in tests with Function::operator() calls (DECSM, DECRM,
DECRQM, SBQUERY) for readability.

Signed-off-by: Christian Parpart <christian@parpart.family>

Author: christianparpart

docs/vt-extensions/semantic-block-query.md

@@ -33,19 +33,21 @@ When disabled:
 - All tracked semantic block data is discarded.
 - The query sequence returns an error response.
 
-## Query Syntax
+## Query Syntax — SBQUERY
 
 ```
 CSI > Ps ; Pn b
 ```
 
+**Mnemonic:** SBQUERY — **S**emantic **B**lock **QUERY**
+
 CSI with `>` leader, final character `b` (for "blocks").
 
-| Ps | Meaning                        | Pn                  |
-|----|--------------------------------|---------------------|
-| 0  | Last completed command block   | ignored             |
-| 1  | Last N completed command blocks| count (default 1)   |
-| 2  | Current in-progress command    | ignored             |
+| Ps | Meaning                         | Pn                  |
+|----|-------------------------------- |---------------------|
+| 1  | Last completed command block    | ignored             |
+| 2  | Last N completed command blocks | count (default 1)   |
+| 3  | Current in-progress command     | ignored             |
 
 ## Response Syntax
 
@@ -95,15 +97,15 @@ That is: `ESC P > 0 b ESC \`
 | `prompt`          | string            | Text content of the prompt region (from Marked line to OutputStart). |
 | `output`          | string            | Text content of the command output region.                        |
 | `exitCode`        | integer           | From OSC 133;D parameter. `-1` if unknown.                       |
-| `finished`        | boolean           | `false` for in-progress commands (Ps=2 query), `true` otherwise. |
+| `finished`        | boolean           | `false` for in-progress commands (Ps=3 query), `true` otherwise. |
 | `outputLineCount` | integer           | Number of output lines in the block.                              |
 
 Text fields use JSON's native encoding for control characters (e.g. `\u001b` for ESC),
 which ensures the payload never contains a raw ST (ESC \) sequence.
 
 ## Example Session
 
-```
+```sh
 # 1. Enable the semantic block protocol
 printf '\033[?2034h'
 
@@ -116,14 +118,14 @@ ls -la
 echo hello
 
 # 4. Query the last completed command
-printf '\033[>0b'
+printf '\033[>1b'
 # Response: DCS > 1 b {"version":1,"blocks":[{"command":"echo hello",...}]} ST
 
-# 5. Query the last 3 commands
-printf '\033[>1;3b'
+# 5. Query the last 3 completed commands
+printf '\033[>2;3b'
 
 # 6. Query any in-progress command
-printf '\033[>2b'
+printf '\033[>3b'
 
 # 7. Disable when done
 printf '\033[?2034l'

src/vtbackend/Screen.cpp

@@ -3501,14 +3501,14 @@ void Screen<Cell>::handleSemanticBlockQuery(Sequence const& seq)
         return;
     }
 
-    auto const queryType = seq.param_or(0, 0); // Ps: 0=last, 1=last N, 2=in-progress
+    auto const queryType = seq.param_or(0, SBQueryType::LastCommand);
     auto const count = seq.param_or(1, 1);     // Pn: count (default 1)
 
     auto const& tracker = _terminal->semanticBlockTracker();
     auto const& completedBlocks = tracker.completedBlocks();
 
-    // Handle in-progress query (Ps=2).
-    if (queryType == 2)
+    // Handle in-progress query.
+    if (queryType == SBQueryType::InProgress)
     {
         auto const& currentBlock = tracker.currentBlock();
         if (!currentBlock || currentBlock->finished)
@@ -3582,8 +3582,8 @@ void Screen<Cell>::handleSemanticBlockQuery(Sequence const& seq)
         return;
     }
 
-    // Handle last completed command(s) (Ps=0 or Ps=1).
-    auto const requestedCount = (queryType == 0) ? 1 : std::max(count, 1);
+    // Handle last completed command(s).
+    auto const requestedCount = (queryType == SBQueryType::LastCommand) ? 1 : std::max(count, 1);
 
     if (completedBlocks.empty())
     {

src/vtbackend/SemanticBlockTracker.h

@@ -17,6 +17,14 @@ struct CommandBlockInfo
     bool finished = false;                  ///< True after OSC 133;D received.
 };
 
+/// SBQUERY (CSI > Ps ; Pn b) query type parameter values.
+struct SBQueryType
+{
+    static constexpr unsigned LastCommand = 1;           ///< Last completed command block.
+    static constexpr unsigned LastNumberOfCommands = 2;  ///< Last N completed command blocks (Pn = count).
+    static constexpr unsigned InProgress = 3;            ///< Current in-progress command.
+};
+
 /// Tracks semantic command blocks when DEC mode 2034 (Semantic Block Reader Protocol) is enabled.
 ///
 /// This is a standalone tracker owned by Terminal, called from Screen::processShellIntegration()

src/vtbackend/ShellIntegration_test.cpp

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
+#include <vtbackend/Functions.h>
 #include <vtbackend/MockTerm.h>
 #include <vtbackend/SemanticBlockTracker.h>
 #include <vtbackend/ShellIntegration.h>
@@ -155,7 +156,7 @@ TEST_CASE("SemanticBlockProtocol.LineFlags")
     SECTION("OutputStart and CommandEnd flags set when mode 2034 is on")
     {
         // Enable mode 2034
-        mc.writeToScreen("\033[?2034h");
+        mc.writeToScreen(DECSM(2034));
 
         // OSC 133;C should set OutputStart on the current line
         mc.writeToScreen("\033]133;C\033\\");
@@ -191,7 +192,7 @@ TEST_CASE("SemanticBlockProtocol.TrackerMetadata")
 
     SECTION("Tracker stores command line and exit code")
     {
-        mc.writeToScreen("\033[?2034h");
+        mc.writeToScreen(DECSM(2034));
 
         mc.writeToScreen("\033]133;A\033\\");
         mc.writeToScreen("$ ");
@@ -209,7 +210,7 @@ TEST_CASE("SemanticBlockProtocol.TrackerMetadata")
 
     SECTION("Tracker disabled clears data")
     {
-        mc.writeToScreen("\033[?2034h");
+        mc.writeToScreen(DECSM(2034));
         mc.writeToScreen("\033]133;A\033\\");
         mc.writeToScreen("\033]133;C;cmdline_url=test\033\\");
         mc.writeToScreen("\033]133;D;0\033\\");
@@ -218,7 +219,7 @@ TEST_CASE("SemanticBlockProtocol.TrackerMetadata")
         CHECK(tracker.currentBlock().has_value());
 
         // Disable mode
-        mc.writeToScreen("\033[?2034l");
+        mc.writeToScreen(DECRM(2034));
         CHECK_FALSE(tracker.currentBlock().has_value());
         CHECK(tracker.completedBlocks().empty());
     }
@@ -231,18 +232,18 @@ TEST_CASE("SemanticBlockProtocol.DECRQM")
     SECTION("DECRQM reports mode 2034 as reset by default")
     {
         mc.resetReplyData();
-        mc.writeToScreen("\033[?2034$p");
+        mc.writeToScreen(DECRQM(2034));
         mc.terminal.flushInput();
         // Response should be CSI ? 2034 ; 2 $ y  (2 = reset)
         CHECK(mc.replyData().find("2034;2$y") != std::string::npos);
     }
 
     SECTION("DECRQM reports mode 2034 as set after enabling")
     {
-        mc.writeToScreen("\033[?2034h");
+        mc.writeToScreen(DECSM(2034));
         mc.terminal.flushInput();
         mc.resetReplyData();
-        mc.writeToScreen("\033[?2034$p");
+        mc.writeToScreen(DECRQM(2034));
         mc.terminal.flushInput();
         // Response should be CSI ? 2034 ; 1 $ y  (1 = set)
         CHECK(mc.replyData().find("2034;1$y") != std::string::npos);
@@ -256,8 +257,8 @@ TEST_CASE("SemanticBlockProtocol.QueryDisabled")
     SECTION("Query without enabling mode returns error DCS")
     {
         mc.resetReplyData();
-        // CSI > 0 b  (query last command)
-        mc.writeToScreen("\033[>0b");
+        // Query last command
+        mc.writeToScreen(SBQUERY(SBQueryType::LastCommand));
         mc.terminal.flushInput();
         // Should get error DCS: ESC P > 0 b ESC backslash
         CHECK(mc.replyData().find("\033P>0b\033\\") != std::string::npos);
@@ -269,7 +270,7 @@ TEST_CASE("SemanticBlockProtocol.QueryLastCommand")
     auto mc = MockTerm { PageSize { LineCount(25), ColumnCount(80) } };
 
     // Enable mode 2034
-    mc.writeToScreen("\033[?2034h");
+    mc.writeToScreen(DECSM(2034));
 
     // Simulate a complete command
     simulateCommand(mc, "$ ", "ls", "file1\nfile2", 0);
@@ -279,8 +280,8 @@ TEST_CASE("SemanticBlockProtocol.QueryLastCommand")
 
     mc.terminal.flushInput();
     mc.resetReplyData();
-    // Query last command: CSI > 0 b
-    mc.writeToScreen("\033[>0b");
+    // Query last command
+    mc.writeToScreen(SBQUERY(SBQueryType::LastCommand));
     mc.terminal.flushInput();
 
     auto const& reply = mc.replyData();
@@ -302,7 +303,7 @@ TEST_CASE("SemanticBlockProtocol.QueryLastNCommands")
     auto mc = MockTerm { PageSize { LineCount(25), ColumnCount(80) } };
 
     // Enable mode 2034
-    mc.writeToScreen("\033[?2034h");
+    mc.writeToScreen(DECSM(2034));
 
     // Simulate two commands
     simulateCommand(mc, "$ ", "cmd1", "out1", 0);
@@ -312,8 +313,8 @@ TEST_CASE("SemanticBlockProtocol.QueryLastNCommands")
     mc.writeToScreen("\033]133;A\033\\");
 
     mc.resetReplyData();
-    // Query last 2 commands: CSI > 1 ; 2 b
-    mc.writeToScreen("\033[>1;2b");
+    // Query last 2 commands
+    mc.writeToScreen(SBQUERY(SBQueryType::LastNumberOfCommands, 2));
     mc.terminal.flushInput();
 
     auto const& reply = mc.replyData();
@@ -328,7 +329,7 @@ TEST_CASE("SemanticBlockProtocol.QueryInProgress")
     auto mc = MockTerm { PageSize { LineCount(25), ColumnCount(80) } };
 
     // Enable mode 2034
-    mc.writeToScreen("\033[?2034h");
+    mc.writeToScreen(DECSM(2034));
 
     // Start a command but don't finish it (no OSC 133;D)
     mc.writeToScreen("\033]133;A\033\\");
@@ -338,8 +339,8 @@ TEST_CASE("SemanticBlockProtocol.QueryInProgress")
     mc.writeToScreen("partial output");
 
     mc.resetReplyData();
-    // Query in-progress command: CSI > 2 b
-    mc.writeToScreen("\033[>2b");
+    // Query in-progress command
+    mc.writeToScreen(SBQUERY(SBQueryType::InProgress));
     mc.terminal.flushInput();
 
     auto const& reply = mc.replyData();
@@ -355,11 +356,11 @@ TEST_CASE("SemanticBlockProtocol.NoCompletedCommands")
     auto mc = MockTerm { PageSize { LineCount(25), ColumnCount(80) } };
 
     // Enable mode 2034
-    mc.writeToScreen("\033[?2034h");
+    mc.writeToScreen(DECSM(2034));
 
     mc.resetReplyData();
     // Query last command when none exists
-    mc.writeToScreen("\033[>0b");
+    mc.writeToScreen(SBQUERY(SBQueryType::LastCommand));
     mc.terminal.flushInput();
 
     auto const& reply = mc.replyData();