feat(renderer): add Mode 2031 dark/light theme detection

[kavhnr]

ResponsiveTUI

Ghostty-capture-20-36-38.mp4

Summary

Adds support for the Mode 2031 terminal protocol, enabling automatic dark/light theme detection and live reactivity to OS appearance changes.

What this does

• Subscribes to theme change notifications (CSI ? 2031 h) during setupTerminal()
• Queries initial theme mode (CSI ? 996 n) on startup
• Parses CSI ? 997 ; 1 n (dark) / CSI ? 997 ; 2 n (light) responses via a new themeModeHandler in the input handler pipeline
• Emits a theme_mode event on the renderer when the mode changes
• Exposes a themeMode getter returning "dark" | "light" | null
• Unsubscribes (CSI ? 2031 l) on destroy, before other cleanup
• Exports a ThemeMode type from types.ts

Supported terminals

• Ghostty 1.0+
• kitty 0.38.1+
• Contour 0.4+
• VTE 0.82+ (GNOME Terminal, etc.)

Unsupported terminals silently ignore the escape sequences — no fallback needed.

Usage

const renderer = await createCliRenderer()

// Read current mode (null if terminal hasn't responded yet)
renderer.themeMode // "dark" | "light" | null

// React to OS appearance changes
renderer.on("theme_mode", (mode) => {
  // mode is "dark" or "light"
})

Design decisions

The implementation follows patterns established by Neovim (PR #31350) and Helix (PR #14356):

Decision	Choice	Rationale
Initial detection	CSI ? 996 n query	Simpler than DECRQM, matches Helix/Contour approach
Dedup guard	Only emit when mode actually changes	Avoids redundant redraws
Cleanup order	Unsubscribe first in finalizeDestroy()	Matches Neovim's terminfo_stop pattern — prevents stale notifications to subsequent processes
Write mechanism	writeOut()	Bypasses interceptStdoutWrite which captures but doesn't forward to the terminal
Handler placement	After focusHandler, before key handler	Same priority tier as other terminal state handlers
Default mode	null	Consumer decides fallback; avoids assuming dark or light

Changes

• packages/core/src/renderer.ts — _themeMode property, themeModeHandler, subscribe/unsubscribe lifecycle, themeMode getter
• packages/core/src/types.ts — ThemeMode type, theme_mode event in RendererEvents

References

• Mode 2031 spec (Contour)
• Neovim implementation (PR #31350)
• Helix implementation (PR #14356)

[pkg-pr-new]

@opentui/core

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core@1a34130

@opentui/react

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/react@1a34130

@opentui/solid

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/solid@1a34130

@opentui/core-darwin-arm64

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core-darwin-arm64@1a34130

@opentui/core-darwin-x64

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core-darwin-x64@1a34130

@opentui/core-linux-arm64

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core-linux-arm64@1a34130

@opentui/core-linux-x64

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core-linux-x64@1a34130

@opentui/core-win32-arm64

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core-win32-arm64@1a34130

@opentui/core-win32-x64

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core-win32-x64@1a34130

commit: 1a34130

[kommander]

Can we do this in terminal.zig setup and shutdown sequences?

[kavhnr]

Yea we can/should. Moved to match how bracketed paste and focus tracking work. It only enables when the terminal actually reports support via DECRPM, which is how Ghostty handles mode activation in its state layer (https://github.com/ghostty-org/ghostty/blob/main/src/terminal/modes.zig) modes get toggled based on detected capability (not sent unconditionally)

Bonus: suspend/resume gets this for free. Updating now.