feat(windows): publish display changes as screen-parameter events (#1573)

Author: y3owk1n

docs/CROSS_PLATFORM.md

@@ -170,7 +170,7 @@ that is what [Known Gaps](#known-gaps) tracks, per
 | Capability                    | macOS                    | Linux X11              | Linux Wayland (wlroots)      | Linux Wayland (KDE)     | Windows                      |
 | ----------------------------- | ------------------------ | ---------------------- | ---------------------------- | ----------------------- | ---------------------------- |
 | **Screen bounds / enumeration** | ✅ Cocoa               | ✅ XRandR              | ✅ xdg-output                | ✅ xdg-output           | ✅ `EnumDisplayMonitors`     |
-| **Display hotplug events**    | ✅ screen-params notif.  | ✅ RandR event fd      | ✅ `wl_output` events        | ✅ `wl_output` events   | 🟡                           |
+| **Display hotplug events**    | ✅ screen-params notif.  | ✅ RandR event fd      | ✅ `wl_output` events        | ✅ `wl_output` events   | ✅ `WM_DISPLAYCHANGE`        |
 | **Focused app identity**      | ✅ NSWorkspace + AX      | ✅ `_NET_ACTIVE_WINDOW` / `WM_CLASS` | ⚠️ app_id only (see below) | ⚠️ app_id only     | ✅ `GetForegroundWindow`     |
 | **App watcher (focus change)**| ✅ NSWorkspace observer  | ✅ event-driven        | ✅ event-driven              | ✅ event-driven         | ✅ `SetWinEventHook`         |
 | **Keymap learns the focused app** | ✅ published by the watcher | ✅ published by the watcher | ✅ published by the watcher | ✅ published by the watcher | ✅ published by the watcher |
@@ -493,8 +493,13 @@ Control events remain macOS-only. Windows has a single API for it after all:
 through `SetWinEventHook` on a message-loop thread of its own, hands each new
 foreground HWND to a goroutine, and resolves it there to the **executable
 path** — the identity `GetForegroundWindow` already gives the focused app, so
-per-app configuration keys on one string however it is learned. Only
-activate and deactivate are emitted there; display hotplug is still a gap.
+per-app configuration keys on one string however it is learned. Display
+changes ride the same dispatch goroutine from a second source: a hidden
+top-level window on a pump thread of its own receives `WM_DISPLAYCHANGE` and
+`WM_DPICHANGED` (`platform/windows/display_watcher.go`) and coalesces them into
+one screen-parameters event, so a resolution or arrangement change re-lays-out
+the overlay as it does on macOS. Only activate, deactivate and screen-params
+are emitted there; launch, terminate and Mission Control stay macOS-only.
 
 **Global hotkeys on Wayland.** No Wayland protocol lets an ordinary client
 register a global hotkey, so Neru reads `/dev/input/event*` directly with a
@@ -869,7 +874,7 @@ important thing to know before touching overlay code:
 | **Always on top**     | `NSScreenSaverWindowLevel`               | `_NET_WM_STATE_ABOVE` + `MapRaised`    | overlay layer                                    | `HWND_TOPMOST`                     |
 | **Focus prevention**  | non-activating panel                     | `override_redirect=YES`                | controlled keyboard interactivity                | `WS_EX_NOACTIVATE`                 |
 | **HiDPI**             | dynamic `contentsScale` + backing-change callback | `Xft.dpi`, one global factor  | `wl_output` scale + `wp_fractional_scale_v1` / `wp_viewporter` | not explicit           |
-| **Multi-monitor**     | per-display clamping, screen-change tracking | all monitors enumerated, per-monitor render, live RandR hotplug | one `wl_surface` per output (max 16), live hotplug | cursor-screen tracking, separate indicator/sticky windows |
+| **Multi-monitor**     | per-display clamping, screen-change tracking | all monitors enumerated, per-monitor render, live RandR hotplug | one `wl_surface` per output (max 16), live hotplug | cursor-screen tracking, live `WM_DISPLAYCHANGE` hotplug, separate indicator/sticky windows |
 | **Buffers**           | layer-backed, OS-managed                 | single Cairo surface                   | triple-buffered SHM pool                         | single pixel buffer                |
 | **Rounded rects / borders** | NSBezierPath                       | Cairo arc path + stroke                | Cairo arc path + stroke                          | software SDF fill + multi-pass stroke |
 | **Text**              | NSFontManager                            | Cairo `select_font_face` / `show_text` | Cairo `select_font_face` / `show_text`           | GDI `CreateFontW` + `DrawTextW` + alpha composite |
@@ -1200,21 +1205,20 @@ working, which is exactly why the build exists.
 
 **Windows**
 
-1. Display hotplug — no screen-parameter change events
-2. Native notifications — no toast support
-3. UIA tree depth — shallow walk; complex apps under-report clickable elements
-4. Grid and recursive-grid transition animation — not implemented
-5. Grid virtual-pointer indicator — a no-op, while recursive grid draws it.
+1. Native notifications — no toast support
+2. UIA tree depth — shallow walk; complex apps under-report clickable elements
+3. Grid and recursive-grid transition animation — not implemented
+4. Grid virtual-pointer indicator — a no-op, while recursive grid draws it.
    `virtual_pointer.ui.*` is therefore partly inert here rather than wholly, so
    it stays declared everywhere and is tracked as this entry instead
-6. Smooth cursor and smooth scroll animation — not implemented
-7. Modifier passthrough and `PostModifierEvent` — no-ops
-8. Horizontal scroll — `ScrollAtCursor` ignores `deltaX`
-9. `monitor_select` mode — returns `CodeNotSupported`
-10. Font resolution — alias mapping only, no system font enumeration
-11. `neru services` — every subcommand returns `CodeNotSupported`, where macOS
+5. Smooth cursor and smooth scroll animation — not implemented
+6. Modifier passthrough and `PostModifierEvent` — no-ops
+7. Horizontal scroll — `ScrollAtCursor` ignores `deltaX`
+8. `monitor_select` mode — returns `CodeNotSupported`
+9. Font resolution — alias mapping only, no system font enumeration
+10. `neru services` — every subcommand returns `CodeNotSupported`, where macOS
     installs a launchd agent and Linux a systemd user unit
-12. IPC endpoint, client side — the daemon's endpoint is scoped to one user on
+11. IPC endpoint, client side — the daemon's endpoint is scoped to one user on
     every platform, but only the Unix client checks that for itself before
     connecting. A named pipe carries no ownership a client can read without
     opening it, so the Windows CLI trusts the name it derives from its own SID.

docs/ROADMAP.md

@@ -43,8 +43,8 @@ The two largest open areas:
 - **Linux** — Wayland global hotkeys, which need `input`-group membership and a
   CGO build rather than missing code, and whose remaining work is failing
   loudly with the remedy.
-- **Windows** — display-hotplug events, which currently block monitor
-  tracking.
+- **Windows** — the remaining Known Gaps entries: notifications, UIA tree
+  depth, animations, horizontal scroll and `monitor_select`.
 
 GNOME Wayland remains unsupported; the daemon refuses to start there. Reviving
 it needs libei plus a GNOME Shell extension — see

internal/adapter/appwatcher/doc.go

@@ -6,5 +6,5 @@
 // platform_other.go as the no-op fallback), so this package compiles on all
 // platforms. On macOS the events come from the Objective-C NSWorkspace
 // observer, on Linux from a compositor or X11 focus source, and on Windows
-// from an EVENT_SYSTEM_FOREGROUND hook.
+// from an EVENT_SYSTEM_FOREGROUND hook plus a hidden window's WM_DISPLAYCHANGE.
 package appwatcher

internal/adapter/appwatcher/platform_windows.go

@@ -21,6 +21,13 @@ import (
 // GetForegroundWindow resolves to for the focused app, so per-app
 // configuration keys on one string whichever way it is learned.
 //
+// Display changes take the same route from a second source: a hidden window
+// (winplatform.StartDisplayWatcher) receives WM_DISPLAYCHANGE and
+// WM_DPICHANGED on its own pump thread, offers a token to a one-slot channel,
+// and the dispatch goroutine turns it into HandleScreenParametersChanged —
+// the event macOS's screen-parameters notification and Linux's RandR fd
+// produce, so the app re-lays-out the overlay the same way on all three.
+//
 // globalWindowsWatcher is the process-wide backend, mirroring
 // globalLinuxWatcher. NewWatcher registers itself here via
 // platformRegisterWatcher.
@@ -33,6 +40,14 @@ var globalWindowsWatcher = &windowsAppWatcher{
 
 		return hook.Stop, nil
 	},
+	subscribeDisplay: func(callback func()) (func(), error) {
+		watcher, err := winplatform.StartDisplayWatcher(callback)
+		if err != nil {
+			return nil, err
+		}
+
+		return watcher.Stop, nil
+	},
 	foreground: func() uintptr {
 		hwnd, _ := winplatform.ForegroundWindowHandle()
 
@@ -47,6 +62,9 @@ type windowsAppWatcher struct {
 	// subscribe installs the foreground hook and returns its stop function;
 	// injectable for tests.
 	subscribe func(callback func(uintptr)) (func(), error)
+	// subscribeDisplay installs the display-change window and returns its stop
+	// function; injectable for tests.
+	subscribeDisplay func(callback func()) (func(), error)
 	// foreground samples the current foreground HWND once at start, so the
 	// keymap has a published app before the first switch.
 	foreground func() uintptr
@@ -58,7 +76,9 @@ type windowsAppWatcher struct {
 	watcher *Watcher
 	stopCh  chan struct{}
 	unhook  func()
-	wg      sync.WaitGroup
+	// unhookDisplay stops the display watcher; nil when it failed to install.
+	unhookDisplay func()
+	wg            sync.WaitGroup
 
 	// lastID and lastName are the most recently dispatched identity ("" means
 	// none focused). Owned by the dispatch goroutine, so they need no lock.
@@ -86,6 +106,7 @@ func (l *windowsAppWatcher) start() {
 	}
 
 	events := make(chan uintptr, 1)
+	displayEvents := make(chan struct{}, 1)
 	l.lastID, l.lastName = "", ""
 
 	unhook, err := l.subscribe(func(hwnd uintptr) { offer(events, hwnd) })
@@ -108,12 +129,24 @@ func (l *windowsAppWatcher) start() {
 	default:
 	}
 
+	// A display watcher that fails to install costs only hotplug: the
+	// foreground hook is already live and the overlay is still re-sized on
+	// each activation, so the watcher runs on without it and says so.
+	unhookDisplay, err := l.subscribeDisplay(func() { offerToken(displayEvents) })
+	if err != nil {
+		l.watcher.logger.Warn(
+			"App watcher: display-change window install failed; overlays follow display changes on the next activation only",
+			zap.Error(err),
+		)
+	}
+
 	l.unhook = unhook
+	l.unhookDisplay = unhookDisplay
 	l.stopCh = make(chan struct{})
 
 	l.wg.Add(1)
 
-	go l.loop(l.stopCh, events)
+	go l.loop(l.stopCh, events, displayEvents)
 }
 
 // stop unhooks first, so nothing offers after the loop is told to exit, then
@@ -127,12 +160,17 @@ func (l *windowsAppWatcher) stop() {
 		return
 	}
 
-	stopCh, unhook := l.stopCh, l.unhook
-	l.stopCh, l.unhook = nil, nil
+	stopCh, unhook, unhookDisplay := l.stopCh, l.unhook, l.unhookDisplay
+	l.stopCh, l.unhook, l.unhookDisplay = nil, nil, nil
 
 	l.mu.Unlock()
 
 	unhook()
+
+	if unhookDisplay != nil {
+		unhookDisplay()
+	}
+
 	close(stopCh)
 	l.wg.Wait()
 }
@@ -156,7 +194,22 @@ func offer(events chan uintptr, hwnd uintptr) {
 	}
 }
 
-func (l *windowsAppWatcher) loop(stopCh <-chan struct{}, events <-chan uintptr) {
+// offerToken is offer for the display channel: a burst of display messages
+// coalesces to a single pending refresh, because the refresh re-reads the
+// display and has nothing to learn from the count. It runs on the display
+// watcher's pump thread.
+func offerToken(events chan struct{}) {
+	select {
+	case events <- struct{}{}:
+	default:
+	}
+}
+
+func (l *windowsAppWatcher) loop(
+	stopCh <-chan struct{},
+	events <-chan uintptr,
+	displayEvents <-chan struct{},
+) {
 	defer l.wg.Done()
 
 	for {
@@ -165,6 +218,8 @@ func (l *windowsAppWatcher) loop(stopCh <-chan struct{}, events <-chan uintptr)
 			return
 		case hwnd := <-events:
 			l.tick(hwnd)
+		case <-displayEvents:
+			l.watcher.HandleScreenParametersChanged()
 		}
 	}
 }

internal/adapter/appwatcher/platform_windows_test.go

@@ -12,6 +12,7 @@ import (
 const (
 	kindActivate   = "activate"
 	kindDeactivate = "deactivate"
+	kindScreen     = "screen"
 
 	hwndNotepad = uintptr(0x10)
 	hwndCode    = uintptr(0x20)
@@ -113,6 +114,41 @@ func (f *fakeHook) fire(hwnd uintptr) {
 	}
 }
 
+// fakeDisplayHook stands in for the hidden display-change window.
+type fakeDisplayHook struct {
+	mu       sync.Mutex
+	callback func()
+	unhooked bool
+	err      error
+}
+
+func (f *fakeDisplayHook) subscribe(callback func()) (func(), error) {
+	if f.err != nil {
+		return nil, f.err
+	}
+
+	f.mu.Lock()
+	f.callback = callback
+	f.mu.Unlock()
+
+	return func() {
+		f.mu.Lock()
+		f.unhooked = true
+		f.callback = nil
+		f.mu.Unlock()
+	}, nil
+}
+
+func (f *fakeDisplayHook) fire() {
+	f.mu.Lock()
+	callback := f.callback
+	f.mu.Unlock()
+
+	if callback != nil {
+		callback()
+	}
+}
+
 func identityFor(hwnd uintptr) (string, string, bool) {
 	switch hwnd {
 	case hwndNotepad:
@@ -125,16 +161,26 @@ func identityFor(hwnd uintptr) (string, string, bool) {
 }
 
 func newTestBackend(hook *fakeHook, foreground uintptr) (*windowsAppWatcher, *eventRecorder) {
+	return newTestBackendWithDisplay(hook, &fakeDisplayHook{}, foreground)
+}
+
+func newTestBackendWithDisplay(
+	hook *fakeHook,
+	display *fakeDisplayHook,
+	foreground uintptr,
+) (*windowsAppWatcher, *eventRecorder) {
 	watcher := NewWatcher(nil)
 	recorder := &eventRecorder{}
 
 	watcher.OnActivate(func(name, bundle string) { recorder.add(kindActivate, name, bundle) })
 	watcher.OnDeactivate(func(name, bundle string) { recorder.add(kindDeactivate, name, bundle) })
+	watcher.OnScreenParametersChanged(func() { recorder.add(kindScreen, "", "") })
 
 	backend := &windowsAppWatcher{
-		subscribe:  hook.subscribe,
-		foreground: func() uintptr { return foreground },
-		identity:   identityFor,
+		subscribe:        hook.subscribe,
+		subscribeDisplay: display.subscribe,
+		foreground:       func() uintptr { return foreground },
+		identity:         identityFor,
 	}
 	backend.register(watcher)
 
@@ -207,3 +253,37 @@ func TestWindowsAppWatcher_Start_HookFailureLeavesWatcherIdle(t *testing.T) {
 
 	recorder.waitFor(t, nil)
 }
+
+func TestWindowsAppWatcher_Start_PublishesDisplayChanges(t *testing.T) {
+	display := &fakeDisplayHook{}
+	backend, recorder := newTestBackendWithDisplay(&fakeHook{}, display, hwndDesktop)
+
+	backend.start()
+	defer backend.stop()
+
+	display.fire()
+	recorder.waitFor(t, []watchEvent{{kindScreen, "", ""}})
+
+	backend.stop()
+
+	if !display.unhooked {
+		t.Fatal("stop did not stop the display watcher")
+	}
+
+	display.fire()
+	time.Sleep(20 * time.Millisecond)
+
+	recorder.waitFor(t, []watchEvent{{kindScreen, "", ""}})
+}
+
+func TestWindowsAppWatcher_Start_DisplayWatcherFailureKeepsForegroundLive(t *testing.T) {
+	hook := &fakeHook{}
+	display := &fakeDisplayHook{err: errHookInstall}
+	backend, recorder := newTestBackendWithDisplay(hook, display, hwndDesktop)
+
+	backend.start()
+	defer backend.stop()
+
+	hook.fire(hwndNotepad)
+	recorder.waitFor(t, []watchEvent{{kindActivate, nameNotepad, pathNotepad}})
+}