Restore Kitty Mode 2031 color-scheme reports

[austinywang]

Summary

Restore the Kitty color-scheme protocol behavior needed by cmux PR ghostty-org#10527 / issue ghostty-org#5490:

• report the current CSI ? 997;N n result immediately when private Mode 2031 is enabled;
• preserve the existing mode-gated unsolicited reports for later appearance changes;
• keep reports on the owning surface and ensure each surface's Termio config uses its own conditional theme state, including when no conditional config rules are present.

The initial report change preserves the contributor's original implementation and attribution from 9fd00e0e4d902f938953fd23d18cb39469f5db5c; the conditional-state correction is cherry-picked from 2be58ee0edf055e6444b074e4a51e9ec29dfb082.

This branch is a fast-forward descendant of current main. It is referenced by cmux PR #10527.

Verification

• zig build test -Dtest-filter='terminal response suppression' --summary all (73/73)
• zig build test -Dtest-filter='color scheme report' --summary all (74/74)
• zig build test -Dtest-filter='changeConditionalState' --summary all (74/74)
• zig fmt --check src/Surface.zig src/termio/stream_handler.zig

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Restores the Kitty color-scheme protocol for mode 2031 so enabling the mode immediately reports the current scheme and later appearance changes report on the owning surface. It also keeps the reported theme aligned with each surface's resolved conditional state, including when no conditional rules are set.

• Mode 2031 now queues a forced report on enable; a shared pending flag suppresses older queued config reports until that authoritative reply is handled, and a same-theme config-refresh report queued right after is dropped as redundant.
• Each surface's Termio config uses its own conditional theme state, so surfaces without conditional rules no longer report a stale light mode.
• Appearance callbacks update the Termio color scheme synchronously and preserve it across queued config swaps, so CSI 996 and Mode 2031 cannot report a stale theme.

^{Written for commit b39533b. Summary will update on new commits.}

Summary by CodeRabbit

• Bug Fixes
  • Improved terminal color-scheme reporting when applications request the current theme.
  • Ensured reports reflect each surface’s active light or dark mode from startup onward.
  • Improved immediate color-scheme responses when the relevant terminal mode is enabled.
  • Prevented duplicate or outdated initial color-scheme reports.
  • Preserved the active color scheme during runtime configuration changes.
  • Improved synchronization during theme transitions and configuration reloads, including when reload actions are suppressed.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: a506eab6-e9a8-4ae8-b051-d7ade19ce4ec

📥 Commits

Reviewing files that changed from the base of the PR and between f03fae7 and b39533b.

📒 Files selected for processing (4)

• src/termio/Termio.zig
• src/termio/Thread.zig
• src/termio/message.zig
• src/termio/stream_handler.zig

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The update preserves the active surface color scheme across termio configuration reloads, synchronizes appearance callbacks with termio state, and suppresses duplicate color-scheme reports after Mode 2031 enables reporting.

Changes

Color Scheme Reporting

Layer / File(s)	Summary
Termio color scheme state src/termio/Termio.zig	changeConfig preserves the current theme during configuration replacement. updateColorScheme updates the theme under the renderer mutex. Termio initializes shared pending-report state.
Surface and configuration state synchronization src/Surface.zig	init and updateConfig apply the surface conditional state to termio. colorSchemeCallback updates termio before it emits the reload action.
Mode 2031 report deduplication src/termio/message.zig, src/termio/stream_handler.zig, src/termio/Thread.zig, src/termio/Termio.zig	Color-scheme report messages now include suppress_duplicate. Mode 2031 queues forced reports with this flag. Termio records the reported theme and suppresses matching stale non-forced reports.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to b3953

The PR restores immediate and surface-correct Kitty color-scheme reports while preserving appearance-change reporting; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant AppearanceCallback
  participant Surface
  participant Termio
  participant StreamHandler
  participant MessageWriter
  AppearanceCallback->>Surface: update config_conditional_state.theme
  Surface->>Termio: updateColorScheme(new_scheme)
  StreamHandler->>Termio: enable report_color_scheme
  StreamHandler->>Termio: queue forced ColorSchemeReport
  Termio->>MessageWriter: queue color-scheme report
  Termio->>Termio: suppress matching stale non-forced report

Loading

Suggested reviewers: mitchellh, rockorager, lawrencecchen

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: restoring Kitty Mode 2031 color-scheme reports.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/5490-color-scheme-protocol

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

No issues found across 3 files

_{You’re at about 92% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

_{Re-trigger cubic}