Support terminal-level progress indicators via OSC 9;4

[mdrxy]

What problem are you trying to solve?

Some terminal emulators support the OSC 9;4 progress-reporting sequence, which lets CLI applications report progress to the terminal UI itself. Terminals may render this in the tab, taskbar, dock, or other chrome, rather than inside the terminal viewport.

The sequence is commonly documented as:

ESC ] 9 ; 4 ; <state> ; <progress> BEL

Where <state> is typically 0 clear, 1 normal progress, 2 error, 3 indeterminate, and 4 warning; <progress> is 0–100 when applicable.

This is useful for long-running Textual apps where the user may switch tabs/windows but still wants to see that the app is progressing.

What solution would you like?

It would be useful for Textual to expose a small API for setting and clearing terminal-level progress indicators, for example something along these lines:

self.app.set_terminal_progress(50)
self.app.set_terminal_progress(None)  # clear
self.app.set_terminal_progress(indeterminate=True)
self.app.set_terminal_progress(75, state="warning")

Textual could emit OSC 9;4 when running in a terminal that supports it, and treat it as a no-op or best-effort escape sequence elsewhere.

Alternatives considered

Applications can write the raw escape sequence themselves, but this has a few downsides:

• It bypasses Textual abstractions around terminal capabilities/output.
• Each app needs to duplicate state validation and cleanup behavior.
• It is easy to forget to clear the progress indicator when the app exits.
• Textual is better positioned to decide whether/when such terminal-control sequences should be emitted.

Prior art

Windows Terminal documents support for the ConEmu OSC 9;4 progress-bar sequence:
https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences

Other terminals and terminal libraries have discussed or added similar support, including VTE/GNOME Terminal, iTerm2, Ghostty, and WezTerm.

[willmcgugan]

If it really doesn't break terminals that don't support it then I don't see why not. It's a nice feature.

Possibly this belongs in Rich. It could also be integrated into Rich's progress bars.