diff --git a/macos/Sources/Features/Terminal/BaseTerminalController.swift b/macos/Sources/Features/Terminal/BaseTerminalController.swift
index ec9ddf83b..c1c350f9d 100644
--- a/macos/Sources/Features/Terminal/BaseTerminalController.swift
+++ b/macos/Sources/Features/Terminal/BaseTerminalController.swift
@@ -233,9 +233,12 @@ class BaseTerminalController: NSWindowController,
         return newView
     }
 
+    /// Move focus to a surface view.
     func focusSurface(_ view: Ghostty.SurfaceView) {
+        // Check if target surface is in our tree
         guard surfaceTree.contains(view) else { return }
 
+        // Move focus to the target surface and activate the window/app
         DispatchQueue.main.async {
             Ghostty.moveFocus(to: view, from: self.focusedSurface)
             view.window?.makeKeyAndOrderFront(nil)