macOS: add `toggle_background_opacity` keybind action

[himura467]

Related Issue: #5047 Discussion: #4664

Investigation

The behavior of iTerm mentioned on the Discussion thread was as follows:

• cmd + u can be used to toggle "Use Transparency"
• The "Use Transparency" toggle operates on a per-surface basis
• The "Use Transparency" state persists even after reloading the config

Summary

Based on the investigation and discussions in the preceding pull requests, this implements the toggle_background_opacity keybind action for macOS with the following specifications:

• Switches background opacity on a per-surface basis
• The background opacity state persists even after reloading the config
• Background opacity switching functionality is also available in Quick Terminal
• Does nothing if background-opacity is set to 1 or higher
• Does nothing if in fullscreen mode

Verification

This functionality has been tested across following scenarios, confirming correct action behavior for:

• Split Window
  • Each split window maintains synchronized background opacity states
• Tab Group
  • Background opacity states do not synchronize between tabs
• Quick Terminal
  • Background opacity states remain synchronized even when windows are closed
• Command Palette

AI Disclosure

This pull request was made with assistance from Claude Code. I reviewed all AI-generated code and wrote the final output manually.

https://github.com/user-attachments/assets/e46ff8f0-42f2-442f-97dd-d5f5c33b10f1

[jcollie]

Even though this is intended to be macOS-only, you'll still need to modify the GTK apprt so that it ignores the new apprt action:

https://github.com/ghostty-org/ghostty/blob/dbe42d9353a578b6425cd7d730b22cdc23869711/src/apprt/gtk/class/application.zig#L722-L739

[himura467]

Even though this is intended to be macOS-only, you'll still need to modify the GTK apprt so that it ignores the new apprt action

Fixed. I missed that. Thank you for pointing it out!

[dkarter]

This is one of the things I implemented in WezTerm with Lua and really missing in Ghostty - Would love to see it merged :)

Thanks for the effort on this!