Skip to content

Commit 075b1ec

Browse files
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/FlutterEngine.mm‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1654,11 +1654,18 @@ - (void)setApplicationState:(flutter::AppLifecycleState)state {
16541654
*/
16551655
- (void)handleWillBecomeActive:(NSNotification*)notification {
16561656
_active = YES;
1657-
if (!_visible) {
1658-
[self setApplicationState:flutter::AppLifecycleState::kHidden];
1659-
} else {
1660-
[self setApplicationState:flutter::AppLifecycleState::kResumed];
1657+
// occlusionState can latch stale on an occlusion->visible transition (same-screen
1658+
// Cmd-Tab / Mission Control), so `_visible` is unreliable here. Resume from
1659+
// NSWindow.isVisible instead — NO for a minimized window, so it won't resume hidden.
1660+
// https://github.com/flutter/flutter/issues/155977
1661+
for (NSWindow* window in [NSApplication sharedApplication].windows) {
1662+
if (window.isVisible) {
1663+
_visible = YES;
1664+
break;
1665+
}
16611666
}
1667+
[self setApplicationState:_visible ? flutter::AppLifecycleState::kResumed
1668+
: flutter::AppLifecycleState::kHidden];
16621669
}
16631670

16641671
/**
@@ -1675,8 +1682,8 @@ - (void)handleWillResignActive:(NSNotification*)notification {
16751682
}
16761683

16771684
/**
1678-
* Called when the |FlutterAppDelegate| gets the applicationDidUnhide
1679-
* notification.
1685+
* Called when the application's occlusion state changes
1686+
* (NSApplicationDidChangeOcclusionStateNotification).
16801687
*/
16811688
- (void)handleDidChangeOcclusionState:(NSNotification*)notification {
16821689
NSApplicationOcclusionState occlusionState = [[NSApplication sharedApplication] occlusionState];

‎engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterEngineTest.mm‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1199,6 +1199,16 @@ @implementation MockableFlutterEngine
11991199
[invocation setReturnValue:&visibility];
12001200
});
12011201

1202+
// handleWillBecomeActive derives visibility from the windows (not from the
1203+
// occlusion state, which can latch stale), so provide a window whose visibility
1204+
// we can toggle independently.
1205+
__block BOOL windowVisible = YES;
1206+
id mockWindow = OCMClassMock([NSWindow class]);
1207+
OCMStub([mockWindow isVisible]).andDo(^(NSInvocation* invocation) {
1208+
[invocation setReturnValue:&windowVisible];
1209+
});
1210+
OCMStub([mockApplication windows]).andReturn(@[ mockWindow ]);
1211+
12021212
NSNotification* willBecomeActive =
12031213
[[NSNotification alloc] initWithName:NSApplicationWillBecomeActiveNotification
12041214
object:nil
@@ -1227,12 +1237,30 @@ @implementation MockableFlutterEngine
12271237
[engineMock handleDidChangeOcclusionState:didChangeOcclusionState];
12281238
EXPECT_EQ(sentState, flutter::AppLifecycleState::kHidden);
12291239

1240+
// Becoming active with an on-screen window resumes even though occlusionState still
1241+
// reads not-visible (the stale-latch case). Regression test for #155977.
12301242
[engineMock handleWillBecomeActive:willBecomeActive];
1231-
EXPECT_EQ(sentState, flutter::AppLifecycleState::kHidden);
1243+
EXPECT_EQ(sentState, flutter::AppLifecycleState::kResumed);
12321244

1245+
// The app is now active and considered visible, so resigning active makes it
1246+
// inactive (not hidden) until a real occlusion notification hides it.
12331247
[engineMock handleWillResignActive:willResignActive];
1248+
EXPECT_EQ(sentState, flutter::AppLifecycleState::kInactive);
1249+
1250+
// Occlusion stays authoritative after a becomeActive resume: a genuine
1251+
// not-visible occlusion notification still hides the app.
1252+
visibility = 0;
1253+
[engineMock handleDidChangeOcclusionState:didChangeOcclusionState];
1254+
EXPECT_EQ(sentState, flutter::AppLifecycleState::kHidden);
1255+
1256+
// Becoming active while no window is visible (e.g. activated with all windows
1257+
// minimized, which does not deminiaturize) must not resume: visibility is
1258+
// derived from the windows, not from the activation itself.
1259+
windowVisible = NO;
1260+
[engineMock handleWillBecomeActive:willBecomeActive];
12341261
EXPECT_EQ(sentState, flutter::AppLifecycleState::kHidden);
12351262

1263+
[mockWindow stopMocking];
12361264
[mockApplication stopMocking];
12371265
}
12381266

0 commit comments

Comments
 (0)