docs updates

macos/Sources/App/macOS/AppDelegate.swift

@@ -86,7 +86,9 @@ class AppDelegate: NSObject,
         return ProcessInfo.processInfo.systemUptime - applicationLaunchTime
     }
 
-    /// Tracks whether the application is currently visible
+    /// Tracks whether the application is currently visible. This can be gamed, i.e. if a user manually
+    /// brings each window one by one to the front. But at worst its off by one set of toggles and this
+    /// makes our logic very easy.
     private var isVisible: Bool = true
 
     override init() {
@@ -572,14 +574,16 @@ class AppDelegate: NSObject,
 
     /// Toggles visibility of all Ghosty Terminal windows. When hidden, activates Ghostty as the frontmost application
     @IBAction func toggleVisibility(_ sender: Any) {
-        for controller in NSApp.windows.compactMap({ $0.windowController as? BaseTerminalController }) {
+        // We only care about terminal windows.
+        for window in NSApp.windows.filter({ $0.windowController is BaseTerminalController }) {
             if isVisible {
-                controller.window?.orderOut(nil)
+                window.orderOut(nil)
             } else {
-                controller.window?.makeKeyAndOrderFront(nil)
+                window.makeKeyAndOrderFront(nil)
             }
         }
-       
+
+        // After bringing them all to front we make sure our app is active too.
         if !isVisible {
             NSApp.activate(ignoringOtherApps: true)
         }

src/apprt/action.zig

@@ -96,7 +96,7 @@ pub const Action = union(Key) {
     /// Toggle the quick terminal in or out.
     toggle_quick_terminal,
 
-    /// Toggle the visiblity of all Ghostty terminal windows
+    /// Toggle the visibility of all Ghostty terminal windows.
     toggle_visibility,
 
     /// Jump to a specific tab. Must handle the scenario that the tab

src/input/Binding.zig

@@ -387,7 +387,11 @@ pub const Action = union(enum) {
     /// configuration file to customize its behavior.
     toggle_quick_terminal: void,
 
-    /// Toggle visibility of all windows
+    /// Show/hide all windows. If all windows become shown, we also ensure
+    /// Ghostty is focused.
+    ///
+    /// This currently only works on macOS. When hiding all windows, we do
+    /// not yield focus to the previous application.
     toggle_visibility: void,
 
     /// Quit ghostty.