From 9546999acb0789a7997fcb067d77a59b00f43b6f Mon Sep 17 00:00:00 2001
From: Felix Martin <mail@felixm.de>
Date: Tue, 2 Jun 2026 12:39:32 -0400
Subject: [PATCH] Clarify null-HWND doc note in ForegroundWindow

---
 internal/winapi/winapi.go | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/internal/winapi/winapi.go b/internal/winapi/winapi.go
index b0c5513..6282306 100644
--- a/internal/winapi/winapi.go
+++ b/internal/winapi/winapi.go
@@ -17,7 +17,8 @@ var (
 // ForegroundWindow returns the current foreground window's handle (as a uintptr
 // so platform-neutral callers need not import windows), its title, and its
 // on-task class (process exe base name; see ClassFromImagePath). ok is false
-// when there is no foreground window (e.g. secure desktop / lock screen).
+// when GetForegroundWindow returns null, which happens transiently during focus
+// changes and some secure-desktop transitions (UAC / lock screen).
 func ForegroundWindow() (hwnd uintptr, title, class string, ok bool) {
 	h := windows.GetForegroundWindow()
 	if h == 0 {