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

[kavhnr]

pr-657.MP4

Summary

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

Supersedes #654 (closed) — this is a clean rewrite addressing the review feedback to move setup/shutdown into the Zig native layer.

What this does

• Subscribes to theme change notifications (CSI ? 2031 h) during enableDetectedFeatures() in terminal.zig
• 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 ThemeMode | null
• Unsubscribes (CSI ? 2031 l) on destroy via resetState()
• Exports a ThemeMode type from types.ts and adds theme_mode to RendererEvents

Supported terminals

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

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

Design decisions

Each decision follows existing patterns in the codebase and/or established implementations in other terminal applications:

Decision	Choice	Justification
Setup/shutdown in Zig	enableDetectedFeatures() / resetState()	Matches how focus tracking (setFocusTracking) and bracketed paste (setBracketedPaste) are toggled — review feedback from #654
setColorSchemeUpdates() helper	Extracted reusable method	Follows setBracketedPaste, setFocusTracking, setModifyOtherKeys pattern exactly
Unconditional enable	if (!self.state.color_scheme_updates) guard	Same approach as bracketed paste (always enabled via hardcoded self.caps.bracketed_paste = true in checkEnvironmentOverrides). Mode 2031 is safe to send unconditionally — unsupported terminals ignore it
DECRPM detection: both 2031;1$y and 2031;2$y	1 = mode set (active), 2 = mode recognized	Consistent with how focus_tracking (1004), sync (2026), and bracketed_paste (2004) all match both response codes in processCapabilityResponse()
Initial detection via CSI ? 996 n	Simpler than DECRQM	Matches Helix and Contour spec approach
Dedup guard	Only emit when mode actually changes	Avoids redundant redraws
Handler placement	After focusHandler, before key handler	Same priority tier as other terminal state handlers (capabilityHandler, focusHandler)
Default mode	null	Consumer decides fallback; avoids assuming dark or light
ThemeMode type in types.ts	Named type export	Consistent with other type exports like CursorStyle, WidthMethod

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"
})

Changes

• packages/core/src/zig/terminal.zig — setColorSchemeUpdates() helper, enable in enableDetectedFeatures(), use in resetState(), broaden DECRPM detection
• packages/core/src/renderer.ts — _themeMode property, themeModeHandler, 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)
• Ghostty mode handling

[pkg-pr-new]

@opentui/core

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/core@846e043

@opentui/react

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/react@846e043

@opentui/solid

npm i https://pkg.pr.new/anomalyco/opentui/@opentui/solid@846e043

@opentui/core-darwin-arm64

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

@opentui/core-darwin-x64

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

@opentui/core-linux-arm64

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

@opentui/core-linux-x64

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

@opentui/core-win32-arm64

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

@opentui/core-win32-x64

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

commit: 846e043