experiments in a post-browser web
analysis: display/monitor handling bug investigation
+210
+210
backend/electron/display-bugs-analysis.md
+210
backend/electron/display-bugs-analysis.md
···
1
+
# Display/Monitor Handling Bug Analysis
2
+
3
+
**Date:** 2026-02-16
4
+
**Symptoms reported:**
5
+
1. Plugging/unplugging/replugging external monitor: all other apps correctly move windows, but Peek windows stay on the wrong screen.
6
+
2. Super glitchy behavior when dragging windows between two screens.
7
+
8
+
---
9
+
10
+
## Bug 1: macOS Display IDs Are NOT Stable Across Unplug/Replug Cycles
11
+
12
+
**Files:** `/Users/dietrich/misc/mpeek/backend/electron/display-watcher.ts` lines 373-403
13
+
**Severity:** HIGH -- This is likely the primary cause of symptom #1.
14
+
15
+
### Root Cause
16
+
17
+
The Phase 2 restore logic in `findMatchingNewDisplay()` tries to match a re-added display by `display.id` first (line 378), then falls back to resolution matching within 5% tolerance (lines 382-401).
18
+
19
+
On macOS (especially Apple Silicon), `CGDirectDisplayID` is **not stable** across unplug/replug cycles. Apple's own documentation and the BetterDisplay project confirm that the display ID is a transient identifier related to the connection's location in the IO registry. If you unplug and replug the same cable, the display **may** get a different ID.
20
+
21
+
This means:
22
+
- Phase 2 ID matching (`addedDisplays.find(d => d.id === home.displayId)`) will often **fail** for the same physical monitor.
23
+
- The resolution fallback at 5% tolerance may work for identical resolution re-plugs but will fail if the display negotiates a slightly different mode or if two displays have similar resolutions.
24
+
25
+
### Why Other Apps Work
26
+
27
+
Native macOS apps use `NSWindow`, which has built-in screen affinity managed by the window server. When a display disconnects, macOS remembers which windows were on it (using stable display UUIDs, not `CGDirectDisplayID`). When the display reconnects, macOS moves those windows back automatically. Peek's `display-watcher.ts` is fighting this native behavior by implementing its own three-phase algorithm that relies on the unstable `CGDirectDisplayID`.
28
+
29
+
### Recommended Fix
30
+
31
+
**Option A (Preferred -- Less Code):** Remove the custom display-change repositioning entirely for the unplug/replug case. macOS already handles window migration correctly for normal `NSWindow`s. The problem is that Peek's `display-watcher` is **overriding** macOS's native behavior. If the display-watcher is doing more harm than good for the standard case, disable Phase 1b and Phase 2 and let macOS handle it natively.
32
+
33
+
**Option B:** Use display UUIDs instead of display IDs. Electron exposes `display.id` which maps to `CGDirectDisplayID`. To get stable identification, use `CGDisplayCreateUUIDFromDisplayID()` via native module or match on a combination of display serial number + vendor ID + model (if Electron exposes these through `Display` object properties).
34
+
35
+
**Option C:** Make the resolution fallback smarter -- instead of 5% tolerance on resolution alone, also factor in display physical arrangement position (which side of the primary display is it on). This would reduce false matches between two similar-resolution displays.
36
+
37
+
---
38
+
39
+
## Bug 2: Popup Windows and Background-Window Children Are NOT Tracked by Display Watcher
40
+
41
+
**Files:**
42
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts` lines 2604-2617 (popup window creation -- NO `trackWindow()` call)
43
+
- `/Users/dietrich/misc/mpeek/backend/electron/main.ts` lines 985-1064 (background window child creation -- NO `trackWindow()` call)
44
+
**Severity:** HIGH
45
+
46
+
### Root Cause
47
+
48
+
`trackWindow()` is only called in one place: the `window-open` IPC handler at `ipc.ts` line 2206. Two other window creation paths never call it:
49
+
50
+
1. **Popup windows** created from webview `window.open()` (ipc.ts line 2604): `popupWin = new BrowserWindow(...)` is created but `trackWindow(popupWin)` is never called.
51
+
52
+
2. **Background window children** created via `setWindowOpenHandler` in `main.ts` (line 985-1064): Windows created through `createBackgroundWindow()` are registered in the window registry but never passed to `trackWindow()`.
53
+
54
+
This means these windows:
55
+
- Have no entries in `_trackedPositions`
56
+
- Cannot be saved in Phase 1 (their tracked position is `undefined`, so they fall through to `preDebBounds` or `currentBounds`, both of which are post-macOS-relocation)
57
+
- Will not be properly repositioned on display changes
58
+
59
+
### Recommended Fix
60
+
61
+
Add `trackWindow(win)` calls after window creation in both paths:
62
+
- `ipc.ts` after line 2639 (popup window): add `trackWindow(popupWin);`
63
+
- `main.ts` inside the `did-finish-load` callback around line 1047: add `trackWindow(newWin);` (requires importing `trackWindow` from `display-watcher.js`)
64
+
65
+
---
66
+
67
+
## Bug 3: Phase 1b Redistribution Fights macOS Native Window Migration
68
+
69
+
**File:** `/Users/dietrich/misc/mpeek/backend/electron/display-watcher.ts` lines 574-598
70
+
**Severity:** HIGH -- This is likely the second major contributor to symptom #1.
71
+
72
+
### Root Cause
73
+
74
+
When a display is removed:
75
+
1. macOS **immediately** moves windows from the disconnected display to the remaining display(s). This happens BEFORE Electron's `display-removed` event fires.
76
+
2. The display-watcher's Phase 1b then **also** tries to redistribute these windows, using the tracked pre-disconnection positions.
77
+
3. Phase 1b calls `repositionWindowGroup()` which calls `win.setBounds()` to move windows to calculated positions on the remaining display.
78
+
79
+
The result is a **double move**: macOS moves the window first, then Phase 1b moves it again (to a potentially different position). This overrides macOS's placement and can put windows in unexpected positions.
80
+
81
+
Then when the display is re-added:
82
+
4. Phase 2 tries to restore windows to their "home display" but fails because display IDs changed (Bug 1).
83
+
5. Windows remain where Phase 1b put them, which may not be where the user expects.
84
+
85
+
### Why Other Apps Work
86
+
87
+
Other apps don't have a Phase 1b. They let macOS handle the migration when a display disconnects. When the display reconnects, macOS moves the windows back (using its own stable display UUID tracking). Peek's Phase 1b breaks this by moving windows to custom-calculated positions that macOS doesn't know about.
88
+
89
+
### Recommended Fix
90
+
91
+
Remove Phase 1b entirely, or make it opt-in only for cases where macOS's native migration clearly fails (e.g., windows ending up completely off-screen). The `isWindowAccessible()` check in Phase 3 already handles the "window is off-screen" case.
92
+
93
+
---
94
+
95
+
## Bug 4: Custom Drag via `setBounds()` IPC Causes Cross-Monitor Glitchiness
96
+
97
+
**Files:**
98
+
- `/Users/dietrich/misc/mpeek/app/page/page.js` lines 246-252, 610-628
99
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts` lines 3194-3205
100
+
- `/Users/dietrich/misc/mpeek/backend/electron/display-watcher.ts` lines 840-865
101
+
**Severity:** HIGH -- This is the primary cause of symptom #2 (drag glitchiness).
102
+
103
+
### Root Cause
104
+
105
+
Peek's page canvas uses a custom drag implementation that calls `setBounds()` via IPC on every `mousemove` event (throttled to ~60fps via `requestAnimationFrame`). This has multiple problems when dragging across monitors:
106
+
107
+
**Problem A: `setBounds()` is async IPC, causing drag lag.** The drag handler in `page.js` (line 620-627) calculates the new window position from `screenX/screenY` deltas and calls `setWindowBounds()`, which does `requestAnimationFrame` -> `api.window.setBounds()` -> IPC to main process -> `win.setBounds()`. This round-trip takes time, during which the mouse has already moved further, creating a rubber-banding/lag effect. This is inherently worse than native `NSWindow` dragging which happens at the window server level with zero IPC overhead.
108
+
109
+
**Problem B: Transparent frameless windows have known Electron bugs when dragged across monitors.** Electron issue #23215 documents that frameless transparent windows dragged across screen boundaries produce visual artifacts (transparent areas turn black). Electron issue #31058 documents that cross-monitor drag behavior is inconsistent with no semi-transparency preview. These are known Electron limitations with transparent windows.
110
+
111
+
**Problem C: `win.on('moved', updateTracking)` in display-watcher fires during drag.** Each `setBounds()` call triggers the `moved` event listener (display-watcher.ts line 857), which calls `updateTracking()`, which does `findDisplayForPoint()` using `_previousDisplays`. During a cross-monitor drag, the window is momentarily "between" displays. If `findDisplayForPoint()` returns `null` (the window center is in the gap between displays or outside any display), the tracked position is NOT updated. When `findDisplayForPoint()` finds a display, it updates `_trackedPositions` to point to the new display. This rapid switching of the tracked display during drag is not harmful per se, but creates unnecessary computation during what should be a smooth drag operation.
112
+
113
+
**Problem D: Pointer coordinate system mismatch across monitors with different scale factors.** If the two monitors have different DPI/scale factors, `screenX`/`screenY` in the renderer may not map linearly to the physical pixel grid across the monitor boundary. The `setBounds()` call uses logical coordinates, but Electron's coordinate handling across monitors with different scale factors has been inconsistent.
114
+
115
+
### Recommended Fix
116
+
117
+
**Short-term:** Use Electron's native `-webkit-app-region: drag` for the navbar instead of custom `setBounds()` dragging. Native drag uses the window server directly and handles cross-monitor transitions correctly. The hold-to-drag-from-webview feature would still need the custom bridge, but at least navbar drags would be smooth.
118
+
119
+
**Long-term:** Investigate whether the canvas model (transparent frameless window + custom drag/resize) can be replaced with a more standard window model that uses native window chrome, at least for the drag operation. The canvas model was chosen for visual reasons (borderless content display), but it comes with significant cross-monitor drag penalties.
120
+
121
+
---
122
+
123
+
## Bug 5: `isWindowAccessible()` Check Is Too Lenient for Canvas Windows
124
+
125
+
**File:** `/Users/dietrich/misc/mpeek/backend/electron/display-watcher.ts` lines 155-158
126
+
**Severity:** MEDIUM
127
+
128
+
### Root Cause
129
+
130
+
`isWindowAccessible()` checks if the window's center-top (title bar area, y + 15px) is on a display. For canvas/transparent windows that are frameless with no OS title bar, checking y + 15 is checking an arbitrary point near the top of the transparent window. Since the actual content (webview) is offset by margins and trigger zone, the "accessible" check might pass even when the visible content is partially off-screen.
131
+
132
+
More importantly, when Phase 3 runs, accessible windows on unchanged displays are **skipped entirely** (lines 695-710). This means if a window was on a display that changed position (e.g., macOS rearranged displays after plug/unplug), but the window's center-top still falls on a valid display, it won't be repositioned. This could leave windows stranded at coordinates that are technically "on a display" but visually wrong.
133
+
134
+
### Recommended Fix
135
+
136
+
For the display-change use case, `isWindowAccessible()` should also verify that a meaningful portion (e.g., 30%+) of the window area overlaps with a display, not just a single point.
137
+
138
+
---
139
+
140
+
## Bug 6: 500ms Debounce May Miss the Window for Pre-Debounce Capture
141
+
142
+
**File:** `/Users/dietrich/misc/mpeek/backend/electron/display-watcher.ts` lines 776-797
143
+
**Severity:** MEDIUM
144
+
145
+
### Root Cause
146
+
147
+
The `onDisplayChange()` function captures pre-debounce window bounds on the FIRST `display-removed` event (line 780-786). However, macOS fires multiple events rapidly during a display change. The pre-debounce capture happens immediately on the first event, which is correct in theory. But the comment at line 71 acknowledges that macOS relocates windows BEFORE the `display-removed` event fires, making the pre-debounce capture "already too late."
148
+
149
+
The code works around this with `_trackedPositions` (continuously updated on `win.on('moved')`), which is the correct approach. But the pre-debounce capture path is still used as a fallback (line 538: `const bounds = tracked?.bounds ?? preDebBounds ?? currentBounds`). If a window is not tracked (Bug 2), it falls back to `preDebBounds`, which are already post-macOS-relocation and therefore **wrong**.
150
+
151
+
### Recommended Fix
152
+
153
+
This is largely mitigated by fixing Bug 2 (ensuring all windows are tracked). The pre-debounce capture path can be kept as a defense-in-depth fallback but should not be relied upon.
154
+
155
+
---
156
+
157
+
## Bug 7: `display-metrics-changed` Does Not Pass `isRemoval=true`
158
+
159
+
**File:** `/Users/dietrich/misc/mpeek/backend/electron/display-watcher.ts` lines 823-831
160
+
**Severity:** LOW
161
+
162
+
### Root Cause
163
+
164
+
The `display-metrics-changed` handler calls `onDisplayChange()` without `isRemoval=true` (line 829). This means if macOS fires a metrics-changed event instead of (or in addition to) a display-removed event, no pre-debounce window bounds capture will occur. In practice, macOS usually fires `display-removed` for actual disconnections, so this is unlikely to cause real issues. But it's a gap in the defensive coding.
165
+
166
+
### Recommended Fix
167
+
168
+
Check if `changedMetrics` includes `'bounds'` and `screen.getAllDisplays().length < _previousDisplays.length` to detect a "virtual removal" and pass `isRemoval=true`.
169
+
170
+
---
171
+
172
+
## Priority Ordering
173
+
174
+
1. **Bug 1 + Bug 3** (HIGH): macOS display IDs unstable + Phase 1b fighting macOS. These together are the root cause of symptom #1 (windows staying on wrong screen after plug/unplug). The simplest fix is to remove Phase 1b and Phase 2 entirely and let macOS handle window migration natively, since macOS already does this correctly for all other apps.
175
+
176
+
2. **Bug 4** (HIGH): Custom `setBounds()` drag is the root cause of symptom #2 (glitchy cross-monitor drag). Fix by using native drag for the navbar.
177
+
178
+
3. **Bug 2** (HIGH): Missing `trackWindow()` calls for popup and background-created windows. Easy fix -- just add the calls.
179
+
180
+
4. **Bug 5** (MEDIUM): `isWindowAccessible()` too lenient for transparent/canvas windows.
181
+
182
+
5. **Bug 6** (MEDIUM): Pre-debounce capture fallback is unreliable. Mitigated by fixing Bug 2.
183
+
184
+
6. **Bug 7** (LOW): `display-metrics-changed` doesn't capture pre-debounce bounds.
185
+
186
+
---
187
+
188
+
## Key Insight: The Display Watcher May Be Doing More Harm Than Good
189
+
190
+
The fundamental architectural issue is that Peek's `display-watcher.ts` implements a complex three-phase algorithm to handle something that macOS already handles natively for NSWindows. Electron's `BrowserWindow` is an NSWindow under the hood. When other apps "just work" with monitor plug/unplug, it's because they let macOS's window server handle the migration using stable display UUIDs.
191
+
192
+
Peek's display-watcher overrides this native behavior with its own algorithm that:
193
+
- Uses unstable `CGDirectDisplayID` for display matching (fails on Apple Silicon)
194
+
- Moves windows during Phase 1b (overriding macOS's native migration)
195
+
- Calls `win.setBounds()` which may interfere with macOS's own window placement
196
+
- Adds complexity (debouncing, pre-debounce capture, suppress mechanism) to work around timing issues that wouldn't exist if the native behavior were used
197
+
198
+
**Recommendation:** Consider making the display-watcher a safety net rather than the primary mechanism. Let macOS handle the standard plug/unplug case natively. Only intervene (Phase 3 style) when a window is truly inaccessible (completely off-screen with no display under its title bar). This would fix both symptom #1 and simplify the codebase significantly.
199
+
200
+
---
201
+
202
+
## References
203
+
204
+
- [Apple CGDirectDisplayID documentation](https://developer.apple.com/documentation/coregraphics/cgdirectdisplayid)
205
+
- [BetterDisplay discussion on display ID instability](https://github.com/waydabber/BetterDisplay/discussions/3628)
206
+
- [MonitorControl issue on CGDirectDisplayID vs serial number](https://github.com/MonitorControl/MonitorControl/issues/961)
207
+
- [Nonstrict blog: Display reconfigurations on macOS](https://nonstrict.eu/blog/2023/display-reconfigurations-on-macos/)
208
+
- [Electron #23215: Transparent window drag artifacts](https://github.com/electron/electron/issues/23215)
209
+
- [Electron #31058: Cross-monitor drag inconsistency](https://github.com/electron/electron/issues/31058)
210
+
- [Electron #46352: Transparent window flickering/ghosting](https://github.com/electron/electron/issues/46352)