From ed39792febc5d9be7e1bea64b56e205e2b260946 Mon Sep 17 00:00:00 2001 From: Hal Frigaard <4559349+HalFrgrd@users.noreply.github.com> Date: Mon, 3 Aug 2026 19:02:49 +0100 Subject: [PATCH 1/2] 2029 and 2030 --- data/decset-modes.json | 248 ++++++++++++++++++++++++ docs/decset/mode1006-sgr-mouse.mdx | 2 + docs/decset/mode2029-passive-mouse.mdx | 91 +++++++++ docs/decset/mode2030-text-selection.mdx | 86 ++++++++ docs/decset/mode2031-color-scheme.mdx | 2 +- docs/decset/mode2048-in-band-resize.mdx | 2 +- 6 files changed, 429 insertions(+), 2 deletions(-) create mode 100644 docs/decset/mode2029-passive-mouse.mdx create mode 100644 docs/decset/mode2030-text-selection.mdx diff --git a/data/decset-modes.json b/data/decset-modes.json index 2c9b41f..f3ab42e 100644 --- a/data/decset-modes.json +++ b/data/decset-modes.json @@ -2833,6 +2833,254 @@ ] } }, + "mode2029_passive_mouse": { + "__compat": { + "title": "Passive mouse tracking", + "description": "Mode 2029 — Mouse tracking while retaining user text selection", + "doc_path": "/docs/decset/mode2029-passive-mouse", + "support": { + "vt100": { + "version_added": false + }, + "xterm": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "ghostty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "kitty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "wezterm": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "foot": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "alacritty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "iterm2": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "vte": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "windows_terminal": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "konsole": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "mintty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "xterm_js": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "putty": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "rxvt_unicode": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "st": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "contour": { + "version_added": true, + "notes": "Supported via Contour PR #882", + "last_scanned": "2026-02-18" + }, + "bobcat": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "mlterm": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "terminology": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "rio": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "tmux": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "screen": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "cy": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "zellij": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "tuios": { + "version_added": false, + "last_scanned": "2026-02-18" + } + }, + "status": { + "experimental": true, + "standard_track": false, + "deprecated": false + }, + "spec_refs": [ + { + "name": "Passive Mouse Tracking Specification", + "url": "https://github.com/contour-terminal/vt-extensions/blob/master/passive-mouse-tracking.md" + } + ] + } + }, + "mode2030_text_selection": { + "__compat": { + "title": "Text selection tracking", + "description": "Mode 2030 — Forwarding user text selections to host app", + "doc_path": "/docs/decset/mode2030-text-selection", + "support": { + "vt100": { + "version_added": false + }, + "xterm": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "ghostty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "kitty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "wezterm": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "foot": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "alacritty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "iterm2": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "vte": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "windows_terminal": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "konsole": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "mintty": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "xterm_js": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "putty": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "rxvt_unicode": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "st": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "contour": { + "version_added": true, + "notes": "Supported via Contour PR #882", + "last_scanned": "2026-02-18" + }, + "bobcat": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "mlterm": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "terminology": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "rio": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "tmux": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "screen": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "cy": { + "version_added": false, + "last_scanned": "2026-02-17" + }, + "zellij": { + "version_added": false, + "last_scanned": "2026-02-18" + }, + "tuios": { + "version_added": false, + "last_scanned": "2026-02-18" + } + }, + "status": { + "experimental": true, + "standard_track": false, + "deprecated": false + }, + "spec_refs": [ + { + "name": "Text Selection Tracking Specification", + "url": "https://github.com/contour-terminal/vt-extensions/blob/master/text-selection-tracking.md" + } + ] + } + }, "mode2031_color_scheme": { "__compat": { "title": "Color scheme reporting", diff --git a/docs/decset/mode1006-sgr-mouse.mdx b/docs/decset/mode1006-sgr-mouse.mdx index a1099c4..5d9450e 100644 --- a/docs/decset/mode1006-sgr-mouse.mdx +++ b/docs/decset/mode1006-sgr-mouse.mdx @@ -117,3 +117,5 @@ printf '\e[?1006l\e[?1000l' - [Button-Event Mouse Tracking — Mode 1002](/docs/decset/mode1002-button-event) — Motion while button is held - [Any-Event Mouse Tracking — Mode 1003](/docs/decset/mode1003-any-event) — Reports all mouse motion - [SGR-Pixel Mouse — Mode 1016](/docs/decset/mode1016-sgr-pixel) — Pixel coordinates instead of cell coordinates +- [Passive Mouse Tracking — Mode 2029](/docs/decset/mode2029-passive-mouse) — Mouse tracking while retaining user text selection +- [Text Selection Tracking — Mode 2030](/docs/decset/mode2030-text-selection) — Forwarding user text selections to host app diff --git a/docs/decset/mode2029-passive-mouse.mdx b/docs/decset/mode2029-passive-mouse.mdx new file mode 100644 index 0000000..005b8ad --- /dev/null +++ b/docs/decset/mode2029-passive-mouse.mdx @@ -0,0 +1,91 @@ +--- +sidebar_position: 24 +title: "Passive mouse tracking" +sidebar_label: "Passive mouse tracking" +description: "Mode 2029 — Mouse tracking while retaining user text selection" +feature_id: "mode2029_passive_mouse" +data_file: "decset-modes" +--- + + + + + +**Passive Mouse Tracking** (Mode 2029) is a DECSET/DECRST mode that allows primary-screen terminal applications (such as shells) to receive mouse press, release, and movement events while allowing the user to select text or scroll with the mouse wheel as normal. + +## Syntax + +``` +CSI ? 2029 h DECSET — Enable passive mouse tracking +CSI ? 2029 l DECRST — Disable passive mouse tracking +``` + + + +## Description + +Traditional mouse tracking modes in terminal emulators capture all mouse interactions, which prevents the terminal from performing local text selection and scrolling. Because of this, primary-screen applications (like shell command lines) rarely enable mouse tracking. + +Passive Mouse Tracking solves this by allowing applications to receive mouse events without overriding default terminal features like mouse text selection and viewport scrolling. + +- **Set** — Enables passive mouse tracking. Sending `CSI ? 2029 h` implicitly activates DEC mode `?1006` (SGR mouse encoding) and `?1002` (Button click event tracking). To also receive mouse motion events, applications can send `CSI ? 2029 ; 1003 h`. +- **Reset** — Disables passive mouse tracking (`CSI ? 2029 l`) and also disables all mouse event modes and mouse event encoding modes in a single sequence. + +### Feature and mode detection + +Use `DECRQM` (`CSI ? 2029 $ p`) to detect if passive mouse tracking is supported. It is considered supported if the terminal replies with state `1` (set) or `2` (reset). + +### Syntax of received events + +Passive mouse tracking exclusively uses SGR mouse transport encoding (`?1006`). The reported events use standard SGR mouse report format: + +- **Mouse Press / Move:** `CSI ? BUTTON_AND_MODIFIER_MASK ; COLUMN ; LINE M` +- **Mouse Release:** `CSI ? BUTTON_AND_MODIFIER_MASK ; COLUMN ; LINE m` + +Where `BUTTON_AND_MODIFIER_MASK`, `COLUMN`, and `LINE` use the same bitwise layout and 1-based coordinate system as SGR mouse mode (`?1006`). + +### Semantics & Constraints + +- **Main page only**: Applications receive mouse events for the active grid page, not for the scrollback buffer. +- **Strict SGR encoding**: Passive mouse tracking mode only works with SGR transport mode (`?1006`). Attempts to select other transport encodings while Mode 2029 is enabled are ignored. +- **Alternate scroll override**: While Mode 2029 is active, Mode 2007 (Alternate Scroll) is inactive (mouse wheel events are not converted to arrow keys). +- **Implicit cleanup**: Disabling other mouse modes also implicitly disables passive mouse tracking to prevent mouse tracking states from accidentally leaking into child processes. + +### Implementation Notes + +- **Mouse Coordinates**: Top-left is reported as (1, 1). If the viewport is scrolled, coordinates reported to primary screen applications are mapped relative to the visible grid area. +- **Preventing Leakage to Child Processes**: Shells should disable mouse tracking (`CSI ? 2029 l`) before launching child processes. + +## Examples + +```bash +# Enable passive mouse tracking (button clicks + SGR encoding): +printf '\e[?2029h' + +# Enable passive mouse tracking with mouse motion reporting: +printf '\e[?2029;1003h' + +# Query support via DECRQM: +printf '\e[?2029$p' +# Terminal response (if supported): CSI ? 2029 ; 1$y (set) or CSI ? 2029 ; 2$y (reset) + +# Disable passive mouse tracking and all mouse modes: +printf '\e[?2029l' +``` + +## Specifications + + + +## Terminal support + + + +## See also + +- [SGR Mouse Encoding — Mode 1006](/docs/decset/mode1006-sgr-mouse) — Extended SGR mouse event format +- [Text Selection Tracking — Mode 2030](/docs/decset/mode2030-text-selection) — Forwarding user text selection ranges to host applications +- [Button Event Mouse Tracking — Mode 1002](/docs/decset/mode1002-button-event) — Tracking mouse press, release, and drag events diff --git a/docs/decset/mode2030-text-selection.mdx b/docs/decset/mode2030-text-selection.mdx new file mode 100644 index 0000000..7c63c06 --- /dev/null +++ b/docs/decset/mode2030-text-selection.mdx @@ -0,0 +1,86 @@ +--- +sidebar_position: 25 +title: "Text selection tracking" +sidebar_label: "Text selection tracking" +description: "Mode 2030 — Forwarding user text selections to host app" +feature_id: "mode2030_text_selection" +data_file: "decset-modes" +--- + + + + + +**Text Selection Tracking** (Mode 2030) is a DECSET/DECRST mode that allows terminal emulators to report user-initiated text selections (e.g. mouse drag selections) directly to the foreground application. + +## Syntax + +``` +CSI ? 2030 h DECSET — Enable text selection tracking +CSI ? 2030 l DECRST — Disable text selection tracking +``` + + + +## Description + +Text Selection Tracking works in tandem with Passive Mouse Tracking (Mode 2029) or standalone to address the needs of primary-screen applications (like shell command lines). + +With Mode 2030, the terminal performs native text selection and rendering as usual, but forwards the coordinates of selected text ranges within the cursor addressable area to the application. This allows applications to track user selection bounds and react to actions (such as deleting selected text when the user presses `DELETE` or performing custom actions). + +- **Set** — Enables text selection tracking (`CSI ? 2030 h`). +- **Reset** — Disables text selection tracking (`CSI ? 2030 l`). Both soft reset (`DECSTR`) and hard reset (`RIS`) restore Mode 2030 to its reset state. + +### Feature and mode detection + +Use `DECRQM` (`CSI ? 2030 $ p`) to detect support. Text selection tracking is supported if the terminal responds with state `1` (set) or `2` (reset). + +### Event Report Syntax + +When text selection changes within the cursor addressable screen area, the terminal sends a report to the application: + +``` +CSI > SelectionMode ; StartLine ; StartColumn ; EndLine ; EndColumn M +``` + +| SelectionMode | Name | Description | +|---|---|---| +| `1` | Linear selection | Single-word or multi-line linear selection. For single-line selection, `StartLine` equals `EndLine`. For multi-line selection, `StartColumn` marks the start on `StartLine`, and `EndColumn` marks the end on `EndLine`. | +| `2` | Full line selection | Complete lines are selected. `StartColumn` is always `1`, and `EndColumn` is set to the total screen width. | +| `3` | Rectangular selection | Block selection where `StartLine` and `StartColumn` mark top-left corner, and `EndLine` and `EndColumn` mark bottom-right corner (inclusive). | + +:::note +Lines outside the cursor-addressable area (such as scrollback history lines) are excluded from reported selection ranges. +::: + +## Examples + +```bash +# Enable text selection tracking: +printf '\e[?2030h' + +# Query mode support via DECRQM: +printf '\e[?2030$p' + +# Example terminal report received when user selects text from line 2 col 5 to line 2 col 15: +# CSI > 1 ; 2 ; 5 ; 2 ; 15 M + +# Disable text selection tracking: +printf '\e[?2030l' +``` + +## Specifications + + + +## Terminal support + + + +## See also + +- [Passive Mouse Tracking — Mode 2029](/docs/decset/mode2029-passive-mouse) — Receiving mouse events without losing native selection capability +- [SGR Mouse Encoding — Mode 1006](/docs/decset/mode1006-sgr-mouse) — Modern mouse event encoding format diff --git a/docs/decset/mode2031-color-scheme.mdx b/docs/decset/mode2031-color-scheme.mdx index 63bff1c..cd82345 100644 --- a/docs/decset/mode2031-color-scheme.mdx +++ b/docs/decset/mode2031-color-scheme.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 24 +sidebar_position: 26 title: "Color scheme reporting" sidebar_label: "Color scheme reporting" description: "Mode 2031 — Light/dark notifications" diff --git a/docs/decset/mode2048-in-band-resize.mdx b/docs/decset/mode2048-in-band-resize.mdx index 0413244..429aceb 100644 --- a/docs/decset/mode2048-in-band-resize.mdx +++ b/docs/decset/mode2048-in-band-resize.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 25 +sidebar_position: 27 title: "In-band resize" sidebar_label: "In-band resize" description: "Mode 2048 — Deterministic notifications" From c85d5b81594160fb275da9c1c50ea32a02593636 Mon Sep 17 00:00:00 2001 From: Hal Frigaard <4559349+HalFrgrd@users.noreply.github.com> Date: Mon, 3 Aug 2026 19:08:08 +0100 Subject: [PATCH 2/2] add sources --- docs/decset/mode2029-passive-mouse.mdx | 1 + docs/decset/mode2030-text-selection.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/decset/mode2029-passive-mouse.mdx b/docs/decset/mode2029-passive-mouse.mdx index 005b8ad..df61ad1 100644 --- a/docs/decset/mode2029-passive-mouse.mdx +++ b/docs/decset/mode2029-passive-mouse.mdx @@ -86,6 +86,7 @@ printf '\e[?2029l' ## See also +- [Passive Mouse Tracking Specification](https://github.com/contour-terminal/vt-extensions/blob/master/passive-mouse-tracking.md) — Original specification on GitHub - [SGR Mouse Encoding — Mode 1006](/docs/decset/mode1006-sgr-mouse) — Extended SGR mouse event format - [Text Selection Tracking — Mode 2030](/docs/decset/mode2030-text-selection) — Forwarding user text selection ranges to host applications - [Button Event Mouse Tracking — Mode 1002](/docs/decset/mode1002-button-event) — Tracking mouse press, release, and drag events diff --git a/docs/decset/mode2030-text-selection.mdx b/docs/decset/mode2030-text-selection.mdx index 7c63c06..3c91630 100644 --- a/docs/decset/mode2030-text-selection.mdx +++ b/docs/decset/mode2030-text-selection.mdx @@ -82,5 +82,6 @@ printf '\e[?2030l' ## See also +- [Text Selection Tracking Specification](https://github.com/contour-terminal/vt-extensions/blob/master/text-selection-tracking.md) — Original specification on GitHub - [Passive Mouse Tracking — Mode 2029](/docs/decset/mode2029-passive-mouse) — Receiving mouse events without losing native selection capability - [SGR Mouse Encoding — Mode 1006](/docs/decset/mode1006-sgr-mouse) — Modern mouse event encoding format