Skip to content

fix(macos): follow pointer events in background windows - #611

Merged
houko merged 2 commits into
mainfrom
fix/macos-background-pointer
Nov 18, 2026
Merged

houko merged 2 commits into
mainfrom
fix/macos-background-pointer

Conversation

@houko

@houko houko commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

macOS stopped receiving hover enter/move/leave events while another application was active, so a window the user had not focused showed no hover and fired no OnMouseEnter/OnMouseMove/OnMouseLeave. Track the pointer with NSTrackingActiveAlways on views and on the surface, whose moves pick hovers over views with no mouse handlers. The surface's moves area subscribes to moves only, not to its own enters and exits. A separate active-app-only area keeps cursorUpdate:, which AppKit does not deliver to an ActiveAlways area.

macOS shows a background app's window with the active app's cursor, so the surface sets cursors only while the app is active: a background move no longer calls -[NSCursor set], which costs milliseconds with a customized pointer and shows nothing. The cursor-update area sets the cursor as the app becomes active under a resting mouse.

Closes #606.

Targets

  • macOS

Windows, Linux and web already follow pointer events without an activation gate; reviewed their hover and cursor paths. Document the shared background-window behavior, and macOS's active-app-only cursor, in the interaction architecture.

Screenshots

None. This changes native event delivery; no visual style changes.

Verification

  • go tool nsgo test ./internal/platform/macos on macOS: 61 passed, 0 failed, 4 skipped.
  • TestPointerTrackingContinuesInBackground fails against main (surface moves 0x246, view areas 0x241/0x243) and passes with the fix. It checks every mouse-listener kind, the surface's moves area (always active, no enter/exit) and the separate cursor-update area.
  • go build ./... and go tool nsgo check -target all (desktop, Android and web), plus -target macos_arm64,macos_x64,ios,ios_simulator on macOS.
  • go tool nsgo test -run 'Layer|Skills|Doc' .: 35 passed.
  • Pointer check on macOS with system-level mouse events (a view with OnMouseEnter/OnMouseMove/OnMouseLeave and a Hover style, and a view with an I-beam Style.Cursor, while a second app is active). With the fix, moving inside, off and back onto the view in the background window reports moves, leave and enter, and the hover tint follows; covering the view with the other app's window reports a leave and uncovering it an enter. Against main, the same moves report nothing. The cursor stays the arrow over the background window on both, and becomes the I-beam as the app is activated with the pointer resting over the I-beam view.

Checklist

  • Conventional Commit title.
  • Interaction architecture updated; CHANGELOG untouched while it is frozen.
  • No new dependencies.

@github-actions github-actions Bot added size/S documentation Improvements or additions to documentation macOS bug Something isn't working labels Nov 17, 2026
@houko
houko force-pushed the fix/macos-background-pointer branch from 2f64df8 to 1350603 Compare November 17, 2026 19:28
macOS shows a background window with the active app's cursor, so the surface's background moves no longer call -[NSCursor set], which costs milliseconds with a customized pointer and shows nothing. The cursor-update area still sets the cursor as the app becomes active under a resting mouse. Correct the interaction architecture, which said background moves set cursors.
@houko
houko force-pushed the fix/macos-background-pointer branch from 1350603 to 6547ea9 Compare November 18, 2026 02:16
@houko

houko commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator Author

Reviewed. Head 6547ea9, already on current main (a4bc57f).

Code: views' tracking areas now use NSTrackingActiveAlways; the surface has an always-active moves-only area (no enter/exit) plus a separate active-app-only NSTrackingCursorUpdate area, since AppKit does not send cursorUpdate: to an always-active area. updateCursor now returns whenever the app is not active, which only removes -[NSCursor set] calls that macOS would not show anyway; cursorUpdate: still repicks through pickHere once the app is active. CHANGELOG untouched, no hard-wrapped lines, no unrelated changes. The interaction architecture doc matches the code.

Tests:

  • go tool nsgo test ./internal/platform/macos on macOS arm64: 61 passed, 0 failed, 4 skipped.
  • TestPointerTrackingContinuesInBackground against main's macos.go: fails with surface moves 0x246 and view areas 0x241/0x243, as expected; passes with the PR.
  • Linux/amd64 host: go build ./..., GOOS=windows go build ./..., GOOS=linux go build ./..., GOOS=darwin go vet ./internal/platform/macos, and go tool nsgo check -target all (macOS, Windows, Linux, Android and web vets) all pass.

Real pointer check on a macOS 27 Mac, with system-level CGEventPost mouse moves against a probe window that has one view with OnMouseEnter/OnMouseMove/OnMouseLeave and a Hover background, and one view with Cursor: CursorText, while a second app instance is the active app:

  • Background window: moving inside the view reports 18 moves, moving off reports a leave and the hover tint clears, moving back reports an enter and the tint returns (checked by screenshot).
  • Covering the resting pointer's view with the other app's window reports a leave; uncovering it reports an enter.
  • Cursor: over the I-beam view of the background window it stays the arrow; activating the app with the pointer resting there turns it into the I-beam. While active, moving between the plain view and the I-beam view switches arrow/I-beam on a fresh launch.
  • Same activation scenario repeated against builds of main, of the PR's first commit and of the head: in most runs the cursor goes back to the arrow when moving onto the plain view after activation; occasionally it stays the I-beam, and that happened on main as well, so it is not caused by this PR.

@houko

houko commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator Author

Reviewed. The only CI failures are unrelated to this change: TestNestedZoomedCanvasIsSharp, fixed on main by #631, and the hosted runner's slow simulator boot, addressed by #634.

@houko
houko marked this pull request as ready for review November 18, 2026 04:42
@houko
houko merged commit 324fe95 into main Nov 18, 2026
28 of 29 checks passed
@houko
houko deleted the fix/macos-background-pointer branch November 18, 2026 04:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation macOS size/S

Projects

None yet

Development

Successfully merging this pull request may close these issues.

macOS: a window the app has not focused reports no mouse moves, and a hovered view keeps its highlight

1 participant