Repository navigation
Commit 075b1ec
authored
[cp-beta] [macOS] Resume app lifecycle on becomeActive to avoid frozen UI after occlusion (#190435)
### Issue Link:
#155977
### Impacted Users:
All macOS desktop end-users and developers of Flutter apps on macOS. The issue reproduces reliably and frequently on macOS desktop apps launched via Finder/LaunchServices when returning to an occluded app on the same screen (e.g. via Cmd-Tab, Mission Control, or clicking away and back).
### Impact Description:
TL;DR: This issue can cause macOS desktop apps to visibly lock up.
When a Flutter macOS desktop app is occluded and then brought back to the foreground on the same screen (e.g. via Cmd-Tab or Mission Control), macOS does not reliably deliver an
`NSApplicationDidChangeOcclusionState` (visible=YES) notification.
Because `_visible` was driven solely by occlusion notifications, returning to the foreground caused `applicationWillBecomeActive` to read a stale `_visible = NO` and resend `AppLifecycleState.hidden` to the engine. Consequently, the framework stays in the `hidden` lifecycle state: animations are muted, frame scheduling is gated off, and no vsyncs are requested, leaving the UI completely frozen and unresponsive even though the window is frontmost and active.
This is a showstopper bug for shipping production macOS Flutter apps.
### Changelog Description:
[flutter/155977] When returning to an occluded macOS desktop app via Cmd-Tab or Mission Control [on macOS], the UI no longer freezes due to missed occlusion notifications.
### Workaround:
Yes. When the app is frozen after returning via Cmd-Tab or Mission Control, clicking the application's Dock icon will bring it back to life (triggering a WindowServer-driven occlusion state update that recovers rendering).
### Risk:
What is the risk level of this cherry-pick?
This patch adds an additional means of updating its `_visible` state from `NO` to `YES` during `handleWillBecomeActive:`, this then triggers frames to start pumping. This does NOT add any additional means to transition the `_visible` state from `YES` to `NO`.
It's simple, properly tested and doesn't introduce any additional bugs.
It's worth noting that this doesn't reasolve ALL bugs in the code; there's still a small bug in the code:
In the case where `_visible` is `YES` and the user minimises the window (which @bdero mentions fires no occlusion notification) and then cmd-tabs back, `handleWillBecomeActive` would result in `kResumed` even though the window is still down in the dock and not on-screen (because the loop find no visible window but leaves the stale `_visible` = `YES` untouched.
This is intentionally NOT fixed in this patch; which addresses only the high priority visual lock up. The impact of the remaining issue is much, much smaller.
### Test Coverage:
Are you confident that your fix is well-tested by automated tests?
### Validation Steps:
1. Build and launch a Flutter macOS desktop app via Finder or `open` (LaunchServices GUI launch) on macOS.
2. Open another application window so that the Flutter app is occluded.
3. Switch away from the Flutter app and then return to it on the same screen multiple times using Cmd-Tab or Mission Control.
4. Verify that upon returning to the frontmost Flutter app, the UI remains responsive, animations continue to play, and new frames render without freezing.
5. Verify that activating the app via Cmd-Tab while all its windows are minimized does not improperly resume rendering.
6. Run the macOS engine unit tests (`FlutterEngineTest`) to verify all lifecycle tests in `HandleLifecycleStates` pass.
<!--
Thanks for filing a pull request!
Reviewers are typically assigned within a week of filing a request.
To learn more about code review, see our documentation on Tree Hygiene: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
-->
- [X ] I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.
**Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.1 parent a0378ad commit 075b1ec
2 files changed
Lines changed: 42 additions & 7 deletions
File tree
- engine/src/flutter/shell/platform/darwin/macos/framework/Source
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1654 | 1654 | | |
1655 | 1655 | | |
1656 | 1656 | | |
1657 | | - | |
1658 | | - | |
1659 | | - | |
1660 | | - | |
| 1657 | + | |
| 1658 | + | |
| 1659 | + | |
| 1660 | + | |
| 1661 | + | |
| 1662 | + | |
| 1663 | + | |
| 1664 | + | |
| 1665 | + | |
1661 | 1666 | | |
| 1667 | + | |
| 1668 | + | |
1662 | 1669 | | |
1663 | 1670 | | |
1664 | 1671 | | |
| |||
1675 | 1682 | | |
1676 | 1683 | | |
1677 | 1684 | | |
1678 | | - | |
1679 | | - | |
| 1685 | + | |
| 1686 | + | |
1680 | 1687 | | |
1681 | 1688 | | |
1682 | 1689 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1199 | 1199 | | |
1200 | 1200 | | |
1201 | 1201 | | |
| 1202 | + | |
| 1203 | + | |
| 1204 | + | |
| 1205 | + | |
| 1206 | + | |
| 1207 | + | |
| 1208 | + | |
| 1209 | + | |
| 1210 | + | |
| 1211 | + | |
1202 | 1212 | | |
1203 | 1213 | | |
1204 | 1214 | | |
| |||
1227 | 1237 | | |
1228 | 1238 | | |
1229 | 1239 | | |
| 1240 | + | |
| 1241 | + | |
1230 | 1242 | | |
1231 | | - | |
| 1243 | + | |
1232 | 1244 | | |
| 1245 | + | |
| 1246 | + | |
1233 | 1247 | | |
| 1248 | + | |
| 1249 | + | |
| 1250 | + | |
| 1251 | + | |
| 1252 | + | |
| 1253 | + | |
| 1254 | + | |
| 1255 | + | |
| 1256 | + | |
| 1257 | + | |
| 1258 | + | |
| 1259 | + | |
| 1260 | + | |
1234 | 1261 | | |
1235 | 1262 | | |
| 1263 | + | |
1236 | 1264 | | |
1237 | 1265 | | |
1238 | 1266 | | |
| |||
0 commit comments