VT extension to query state and request realtime reports on future state changes

[christianparpart]

Hi @j4james, @dankamongmen, @\all

I want my TUI apps (especially text editor) to change dark/light mode live whenever the OS configuration changes. However, not just TUI apps could benefit from that but also more colorful CLI apps like bat that don't just use the primary colors to produce the colord diff but truecolor. I imagine that such tools could chedk dark mode first before deciding what colors to use.

I want to introduce a VT sequence for that to:

• query current mode (dark or light)
• inform the TE that it should send update dark/light mode color preference change notifications whenever it changes (e.g. similar to focus or mouse event reportings)

I'm pretty sure i'll add that, but i'd like to get your feedback as well before going into an entirely different direction :)

refs PR #1233

What I'm currently having as PoC in the above PR is:

• new DEC mode 2031 (Dark Mode) that indicates dark mode if enabled, and non-dark mode (e.g. light mode) if not
• new VT sequence extension to watch on any DEC mode change with syntax CSI < Ps $ p where Ps can be zero or more DEC mode numbers. Zero (similar to SGR) will reset all watches, and otherwise Ps is a DEC mode to start watching on. The result looks intentionally very similar to DECRPM, that is: CSI < Pd ; Ps $ y with Pd being the DEC mode that has changed, and Ps as 1 to indicate set and 2 to indicate reset.

I am not sure if feature detection is actually required for the new VT sequence extension (it simply won't report) and the new DEC mode can be detected just like any other DEC mode (via DECRQM).

[mitchellh]

Feedback on the two items separately.

DEC Mode 2031

Is there another example of a DEC mode being used to communicate externally controlled state? My [admittedly small] experience is that DEC modes are used to query and change on/off terminal configurations. App theme seems more like an external event such as mouse state.

On the other hand, the supportive argument could be that xterm allows configuring the default value of modes using a Xresources file and you could in theory query them at runtime to find their default state! I'm just playing both sides.

I have some worries about using a mode about this for other reasons: a mode can only represent 1 bit of information. Apple already has 4 system themes (dark, light, dark high contrast, light high contrast). This mode would force terminals to make some decision about what constitutes light and dark... admittedly not too hard today, though.

No comment on number choice, I didn't look into the merits of 2031.

Overall: I think I'm fine with it! 😄 The broad "dark vs light" feels like enough information without getting into the weeds. And a mode is easy enough to support and integrate.

Alternate background, not a formal proposal: Querying some app or system state feels more similar to DECRQSS and family¹² to me. And notification feels more similar to the mouse tracking modes (1000, 1001, etc.) to me. I don't think there's ever been a sequence that combines those things so I realize they don't individually solve your entire problem statement.

DEC Mode Change Notification

My suggestion would be to remove the Ps argument and just make CSI < $ p and change the semantics to just report any mode change. My argument: mode changes are relatively rare, so the performance cost on both the TE and App side of processing a sequence for every mode change is low. I think the burden of forcing TEs to keep track of what modes to notify on and Apps to report those modes is worse.

In the weird scenario where there is a user DoS-ing their own terminal scenario by rapidly flipping some mode, the terminal emulator is free to coalesce the changes over a period of time before reporting. That would be an optional QoL improvement that doesn't impact the protocol.

Further, by only proposing CSI < $ p now, it doesn't preclude proposing Ps in the future if that ever becomes an issue, they're not mutually exclusive, so we should do the simple thing (removing Ps) first which I believe is supported on its own merits?

Otherwise, I like it. 👍

Footnotes

1. https://invisible-island.net/xterm/ctlseqs/ctlseqs.html ↩

2. https://vt100.net/docs/vt510-rm/DECRQSS.html ↩

[j4james]

Just brainstorming some ideas here.

1. You could use a DSR request/response pair to query the state. Typically this form of DSR would use numbers ending in 6 and 7 (see the keyboard status report, and the locator type report). For example, it could be something like this:

   CSI ? 996 n      Query from the host to the terminal requesting the day/night mode.
   
   CSI ? 997;0 n    Terminal response indicating the mode is unknown or unsupported.
   CSI ? 997;1 n    Terminal response indicating daytime mode.
   CSI ? 997;2 n    Terminal response indicating night mode.
   

   The reason I thought DSR might be appropriate is because the ANSI/ECMA standards actually allowed for DSR reports to be sent from the terminal without necessarily being requested by the host, so there is precedence for that kind of thing. Also, DEC defined controls for enabling and disabling unsolicited DSR reports on some of their printers using the following sequences:

   CSI ? 1 n    Disables all unsolicited status reports
   CSI ? 2 n    Enables unsolicited brief status reports
   CSI ? 3 n    Enables unsolicited extended status report
   

   I think these were originally used for error reports, but it doesn't seem unreasonable to extend that behavior to cover other DSR reports too.

2. Another approach would be something based on the format of the DECREQTPARM query. Esentially just a CSI sequence with a parameter that specifies whether you're making a one-off request, or you're allowing the terminal to send unsolicited responses. An example sequence based on that design might look something like this (using -z as the final string)

   CSI 0 -z       Request the day/night mode and allow unsolicited reports.
   CSI 1 -z       Request a single report and disable any more unsolicited reports.
   
   CSI 2; Pn -z   An unsolicited response from the terminal.
   CSI 3; Pn -z   A one-off response in reply to a CSI 1 -z request.
   

   Pn would be the day/night state, e.g. 1 for day, 2 for night, and 0 for unknown.

3. The last idea I had was to use a more straightforward query/response sequence which doesn't deal with the notion of unsolicited reports at all. But then you have a separate sequence that enables/disables unsolicited reports as a global concept.

   The reason I think this approach is interesting, is because unsolicited reports could be useful in a number of scenarios outside day/night mode. For example, an editor might be interested in knowing when the user has switched their color scheme, so it could adjust its syntax highlighting to match. If there was a way to request unsolicited reports in general, the terminal could send something like an OSC palette report whenever the color scheme changed.

   There was actually already a mode defined in the ANSI/ECMA specs that seems like it might be appropriate for this: SRTM (status report transfer mode). When disabled, status reports in the form of DCS are not generated automatically. When enabled, status reports in the form of DCS are included in every data stream transmitted. I might be misinterpreting what that was meant for, but I thought it was worth considering.

[christianparpart]

I very much like the idea of DSR amongst all of your proposals. I suggest to continue with solution 1 of your proposal then and create a commit for that.

(Side note, if we'd ever come up with a solution to produce a VT sequence to report screen size changes, then going for a DSR in that regard would make sense as well, also to keep things in line.)

[rockorager]

   The reason I think this approach is interesting, is because unsolicited reports could be useful in a number of scenarios outside day/night mode. For example, an editor might be interested in knowing when the user has switched their color scheme, so it could adjust its syntax highlighting to match. If there was a way to request unsolicited reports in general, the terminal could send something like an `OSC` palette report whenever the color scheme changed.

I think in general this mode should only report palette changes. Consider the case where I have my OS change light/dark mode on a timer but I don't change my terminal theme. If a TUI gets a signal I've changed to light mode, and starts emitting characters with the default background (which it thinks is a light color? Unless it's also querying for the palette after such a notification) I will have some very difficult to read text.

In either case, the TUI should only actually care if the terminal palette has changed. I would think this could be done with a single CSI to notify of palette change, and then it's up to the TUI to request the new palette, if it wants it.

That said, I think this is a great addition!

[dankamongmen]

would also love to have palette change notifications; this would close a hole in notcurses

[christianparpart]

To all, I'm very positively impressed by the feedback we've gathered here. I didn't have much time past 21 hours, but I'm sure we'll get to something. I think also we should not mandate exclusively dark/light color mode but simply notify the TUI/app that the color palette has changed. Is this also in your interest, @dankamongmen?

[dankamongmen]

much prefer general palette change notification, aye. following any such event i will recover the palette.

recovering the palette in toto is an intensive operation. it might or might not be worth indicating which elements have been invalidated. that probably is not a great thing to do when all of them get changed unless you have a range, which maybe isn't a problem.

[rockorager]

I would also like unsolicited reports on terminal size please. This could simplify some differences in windows vs Mac/unix APIs for SIGWINCH

[rockorager]

I think a combination of @j4james and @christianparpart approaches would work pretty well:

DEC MODE 2031 Enable unsolicited terminal palette updates. Keeping this as a DEC mode is great for feature detection and is very usable to enable / disable the feature. I like @j4james proposal to use the DEC feature of DSR which already exists, but that doesn't help me know which reports I will be receiving. Keeping each report as a specific mode lets me know which reports I can enable on any given terminal.

The reply:

CSI ? 2031 n A device status report makes perfect sense, and can even respond with the DEC MODE. All this does is alert the application that the palette has changed in some way. The application is free to query any of the color values it cares about (neovim -> background color).

It's important that this also respond to palette changes caused by OSC 4, 10-19. Applications such as theme.sh could be run inside neovim to change to a light mode, and neovim could then pick up the change from the DSR response and update it's color scheme to match.

---

This is pretty easily extended to terminal size

DEC MODE 2032 Enable unsolicited terminal size reports

CSI ? 2032 n as the response that the size has changed. The application can query the size (in characters and/or pixels) depending on what they need.

[rockorager]

I like the simplicity of this approach, but I'd be concerned that the additional round-trip (notification -> query -> response) would make it unusable for potentially high-frequency reports like a size change notification.

This is pretty close to what's happening now, right?

Size change -> TE resizes PTY with syscall -> application receives SIGWINCH -> TUI queries size from TE or with a SYSCALL -> response

[j4james]

I think one sequence to enable all reports would work as long as I am able to determine what types of reports I can expect to receive.

I definitely agree this is a problem, especially since you don't necessarily know what format these reports might take (DSR, DCS, OSC, etc). But if we need to identify what events you've subscribed to, we might as well let the app request those events explicitly, and not bother with the terminal response.

Either way, the complication is in coming up with an easily extensible method for identifying the events. I don't think a simple number is a practical solution. If a random terminal decides they want to add a new event, there's no standards organization where they can register a number for that.

I was thinking we could maybe use a technique similar the DECRQSS queries, where you describe the notification you want to receive in terms of its final character sequence, along with a parameter value describing the sequence type (i.e. CSI, OSC, DCS). But that seems like it could be a bit heavy if there are a lot of events you may be interested in.

I don't know. I don't have a great solution for this.

Size change -> TE resizes PTY with syscall -> application receives SIGWINCH -> TUI queries size from TE or with a SYSCALL -> response

My understanding was that SIGWINCH included the size in the notification, so there should be no need for the app to query the size from the terminal. User sizes the window -> terminals sends SIGWINCH -> app adjusts it's UI to fit the updated size.

[j4james]

Another idea: how about a kind of wrapper mode that indicates that you want the terminal to enable unsolicited reports for all the query sequences that follow. I'm not sure a mode is appropriate for this, but just for argument's sake, let's use mode ?9999.

1. CSI ? 9999 h // unsolicited mode enabled
2. OSC 10 ; ? ST // request foreground color
3. DCS $ q SP q ST // request cursor style
4. CSI ? 9999 l // unsolicited mode disabled
5. CSI 6 n // request cursor position

The terminal should then respond with the foreground color, the cursor style, and the active cursor position. But it also now knows that you want unsolicited reports for the foreground color and cursor style when updated by the user, but it shouldn't send unsolicited cursor position reports.

To disable all unsolicited reports, you could maybe turn the mode on and off with nothing between. Or possibly just receiving the CSI ? 9999 l sequence without a previous CSI ? 9999 h sequence would be enough.

[rockorager]

I like the wrapper. The only issue I can see is discovering which queries a TE supports unsolicited updates for. For example, a TE could support the mode for palette changes but not for screen size. I might issue the query for screen size while the mode is enabled but I wouldn't really be sure I'll get updates.

It seems this comes down to two main requirements:

1. We need a way to tell the terminal which query we want unsolicited reports for, and in the case of the palette query we don't have a generalized query for the entire palette
2. The terminal needs a way to tell us which queries it can send unsolicited reports for

Realistically, this only needs to cover external events. I don't know that supporting unsolicited cursor position reports, unsolicited mouse mode reports, etc are of any value...the application is in control of these and should have a reasonable expectation that they won't change out from underneath the app.

[j4james]

The only issue I can see is discovering which queries a TE supports unsolicited updates for.

Does that really matter though? I would have thought of these reports as a bonus feature for the app, but not essential for it to function. Like do you really care if your app is not going to receive day/night notifications, or palette updates? What could you do differently if you knew a particular report wasn't going to be supported by the terminal?

in the case of the palette query we don't have a generalized query for the entire palette

Typically I suspect apps would only care about the default foreground and background colors. Or if they need more than that, it's probably just the primary 16 colors, which could be retrieved with a query like this:

\e]4;0;?;1;?;2;?;3;?;4;?;5;?;6;?;7;?;8;?;9;?;10;?;11;?;12;?;13;?;14;?;15;?\e\\

Not pretty, but doable. And if you really need the full color table there's also a DECCTR query you can use (\e[2;2$u). But I suspect that's not as widely supported, and the color resolution is lower (although I doubt that's a concern for most use cases).

Realistically, this only needs to cover external events. I don't know that supporting unsolicited cursor position reports, unsolicited mouse mode reports, etc are of any value

Agreed, but it's nice to know that it could potentially work with any query sequence if there was ever a use case for that. I think that's preferable to a hard-coded list of supported queries.

Although at this point I suspect @christianparpart may be thinking this is overkill for his needs. But I'm just throwing out ideas here. Feel free to ignore me.

[christianparpart]

Hey guys. I am pretty much on the side of keeping it simple. Since DSR is already established, I am in favor of extending this in a way @j4james suggested.

While @dankamongmen (and @j4james?) had a good point that simply reporting palette changes should be sufficient, I was at first a great fan of that idea. That is what the unsolicited DSR will be about. However, it may make sense -for simplicity- to simply ask for day/night mode by the TUI or evne CLI to quickly decide what colors to chose. I keep having delta as a great example here, because that could simply check that and then decide what color scheme to pick.

Proposal: explicit request

CSI 996 n       (DSR with new DEC param) query current day night mode
                terminal responds with:
                   CSI ? 996 ; 1 n      for night mode
                   CSI ? 996 ; 2 n      for day mode

Proposal: unsolicited reports

Looks exactly like the reply from DSR above, except that it was generated unsolicited and not actively requested. The day/night mode param is IMHO to be taken as a hint - in my PoC implementation, I'm inferring that value based off the default text foreground color using the algorithm that was suggested also in the MS documentation how how to infer dark/light mode

See https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/apply-windows-themes
and its use and definition of the function IsColorLight.

I personally seem to prefer that, because it's more reliable to what the user/TUI tries to achieve, and it covers more color palette changes than simply dark/light (day/night) but also the in betweens.

The proposed patch for Contour would look like this: abb0e18

p.s.: applications receiving unsolicited DSR on color palette update (regardless of source that triggered it) may ignore the dark/light (night/day) mode hint and simply query and/or overwrite the palette if they need to (notcurses e.g.?) Other than that, I see great potential for standard CLI apps on the explicit request and for TUI apps like vim to reflect the colorscheme in realtime whenever the dark/light mode of the OS is changing (that was my whole motivation of getting here :) )

[j4james]

Note that DSR response numbers need to be different from the query, i.e. the app should send 996 to query the terminal, and the terminal should respond with 997. But feel free to use different numbers if you don't like 996/997. Just make sure the final digits are 6 and 7.

[christianparpart]

Applied. It's 996/997 now. I don't mind the number as long as the proposal as a whole looks adoptable by others. :)

NB: Why do they must end on 6 and 7?

[christianparpart]

Documentation for the extension is now also on https://contour-terminal.org/vt-extensions/color-palette-update-notifications/

Thanks for all the valuable feedback we've gotten so far.

If I was missing anything in the documentation page above, or did any other mistake, please raise your ✋. I'd also be interested in others that would like to adopt that. :-)

[j4james]

NB: Why do they must end on 6 and 7?

That's just a convention which helps to indicate the meaning of the number, similar to the way you can tell a 2xx status in HTTP is good, a 3xx is a redirect, and 4xx or 5xx are errors.

A DSR number ending in 5 is typically a status request (i.e. a check to see if something working), and the correpsonding number ending in 0, 1, 2, 3, or 4 is the response (0 is good, while the others are errors). A number ending in 6 is typically an information request, and the corresponding number ending in 7 would be the response (assuming it has a DSR response).

Example status queries:

• DSR 5 with responses 0 and 3.
• DSR ?15 with responses ?10 ?11 and ?13.
• DSR ?25 with responses ?20 ?21 and ?23.

Example information queries:

• DSR ?26 with the information reported in DSR ?27.
• DSR ?56 with the information reported in DSR ?57.
• DSR 6 with the information reported in a CSI response.

You don't have to follow that convention, but I'd recommend it. And you definitely don't want to have the query and the response using the same numbers, because that can lead to an infinite feedback loop.

[christianparpart]

Many thanks.

We can stick with 996 and 997 now. I've merged it to master, though, we won't release by tomorrow anyways. And in case we believe it was ground breakingly wrong, we can always change :)