TerminalColor

Terminal color detection. The PHP port of pi-tui's `terminal-colors.ts`. Parses the responses a terminal sends back to OSC 11 (query background color) and DECSET 997 (query color scheme) so a TUI can auto-theme itself: pick a dark or light {@see TerminalTheme} based on the actual background the terminal is using, instead of guessing from a hardcoded default. The flow is: the app emits `\x1b]11;?\x1b\\` (OSC 11 query) and optionally `\x1b[?997$n` (color scheme query); the terminal replies asynchronously with the sequences these helpers recognize. The loop's input path feeds those replies to {@see isOsc11BackgroundColorResponse()} / {@see parseOsc11BackgroundColor()} / {@see parseTerminalColorSchemeReport()} and the app swaps its theme accordingly. Pure utility — no state, no I/O. The loop or a bootstrap harness owns the timing of the queries; this class only knows how to recognize and parse the replies.

public static function isOsc11BackgroundColorResponse(string $data): bool

Whether this input is the terminal's OSC 11 reply reporting its background colour, which arrives on the input stream and must not be treated as a key.

Parameters

public static function parseOsc11BackgroundColor(string $data): ?array

Parses an OSC 11 background-color reply into an `{r, g, b}` array (each 0–255), or `null` when the reply is malformed or uses an unsupported format. Accepts the three forms xterm/iTerm/Kitty emit: `#RRGGBB`, `#RRRRGGGGBBBB` (16-bit per channel), and `rgb:RR/GG/BB` (with optional `rgba:` prefix).

Parameters

public static function parseTerminalColorSchemeReport(string $data): ?string

Parses a DECSET 997 color-scheme report (`\x1b[?997;Nn`) into {@see SCHEME_DARK} or {@see SCHEME_LIGHT}, or `null` when the input is not a color-scheme report.

Parameters

public static function isLightBackground(int $r, int $g, int $b): bool

Returns whether the given RGB background color is "light" by computing perceived luminance — the same heuristic pi-tui uses to pick a theme when only the background color is known (no explicit DECSET 997 report). A background is light when its relative luminance exceeds 0.5.

Parameters