Reading the host terminal's colours
Subscribing to the terminal's own palette from React, including the DEC mode OpenTUI never enables and the cache the poll fallback has to clear.
- #opentui
- #features
- #colour
A terminal app that picks its own colours clashes with the scheme the user already chose. The alternative is to paint with the colours the terminal reports: its default foreground and background, plus the sixteen ANSI entries.
OpenTUI does the protocol work. renderer.getPalette() queries the terminal
with OSC 10 and 11 for the foreground and background and OSC 4 for the palette,
and the renderer emits a palette event when the colours change. What is
missing is a React adapter, a neutral shape to hand the rest of the app, and
three details that decide whether the app ever notices a live theme switch.
The palette type
Everything downstream reads this rather than OpenTUI's TerminalColors, so the
colour-to-role mapping stays free of any renderer import:
Any entry can be null. A terminal answers only the queries it supports, so
code that assumes all eighteen colours are present will read null as a
colour.
The app has to enable mode 2031
OpenTUI reacts to the terminal's colour-scheme-change notification and never turns the notification on. DEC private mode 2031 is what asks for it:
Without the write, a modern terminal never reports a change, the palette
event never fires, and the app holds its startup colours until a restart. With
it, switching the terminal's theme repaints within a frame.
Write to process.stdout. OpenTUI's output backend is the same stream the
renderer drives, and renderer.stdout is private. The disable goes in the
effect cleanup, so the app does not leave the mode set in the user's terminal
after it exits.
The poll has to clear the palette cache
Terminals without 2031 need polling, and getPalette() caches. Re-querying
without clearing the cache returns the colours from startup forever, which
looks the same as a terminal that does not support live changes:
An earlier version stopped the poll once a live event had proved the terminal
reports changes. That was a bug. The first palette event can arrive for
reasons unrelated to 2031 support, and a terminal that then stops reporting
leaves the app with no mechanism at all. Polling once a second with a cache
clear costs one escape-sequence round trip, and update drops anything that
matches the last fingerprint, so nothing touches React state between real
changes.
A terminal mid-switch answers nothing
During a theme switch a terminal can briefly reply with every colour null.
Treating that as a palette flashes the UI to its empty-palette fallbacks for a
frame, so hasColour rejects it and the hook keeps the last good palette:
Colours before the first paint
A hook cannot help with frame one, because its effect runs after it. The export for that is a one-shot query the entry point can await before it mounts anything:
On a real TTY, OpenTUI has usually already detected the palette during
createCliRenderer, so this returns from cache immediately. The 200 ms timeout
is for the terminal that goes quiet; null means the hook will fill it in
shortly and the caller renders its fallback until then.
The module
Using it
The entry point pre-fetches and hands the result down; the hook keeps it current from there:
One subscriber is enough for a whole app. Put the hook in the provider that owns colour and let components read the resolved palette from context, rather than calling it in several places and paying for several polls.
What a pipe cannot tell you
A non-TTY cannot answer an OSC query, and OpenTUI swallows process.stdout
writes when it is not driving a terminal. So a test cannot verify live palette
detection headlessly. It can cover toPalette, hasColour and the
fingerprint, and the rest needs a real terminal and a theme switch while the
app is running.
Do not use renderer.setBackgroundColor() to apply the colours. It emits
OSC 11 to change the terminal's actual background, which races the terminal's
own transition and flashes a stale colour for a frame on every change. Paint a
full-screen box at the app root instead; it draws into the render buffer and
leaves the terminal alone.
Related entries
- A theme that follows the terminal. Maps this palette onto semantic colour roles, and decides light or dark from the background.
Related entries
A theme that follows the terminal
Semantic colour roles over a static catalogue and the live terminal palette, with light and dark read from the terminal background rather than declared.
Clipping box borders
OpenTUI's native box draw ignored the scissor stack, so a bordered box painted its border over everything around its scroll container. Fixed upstream in 0.6.0; kept for the detour it describes.
Making drag-selection opt-in
OpenTUI's text renderables are selectable by default, so a click-to-navigate UI starts a drag-selection instead. Flipping the default without disabling selection.