Mac Platform: Use permanent thin controller solution on macOS 13+
Moderate
Commit Hash:
54da6b2481d3ef4841a7e9f5081e9597371e8ec8
Commit Time: 2025-03-07 00:55:53+00:00
Impact Level: Moderate
Generated By: webview2-upstream-sentry
Upstream Review:
View Upstream Review 🔗
📋 Summary
This submission reintroduces the approach of “always adding a permanent thin titlebar accessory view controller for windows on macOS 13 and above” to address the issue where, in immersive fullscreen mode, the titlebar accessory view controller for PWA (Progressive Web App) windows is inserted too late during fullscreen, resulting in abnormal macOS system fullscreen behavior (such as auto-hide failure). Specifically, the previous kFullscreenPermanentThinController feature flag has been removed, and the decision to permanently insert the thin controller is now directly based on the macOS version (>=13). For macOS 12 and earlier versions, the old logic of inserting/removing the thin controller as needed is still used. This change involves core window and immersive fullscreen control code in remote_cocoa’s browser_native_widget_window_mac.mm, immersive_mode_controller_cocoa.{h,mm}, and related files.
🎯 Impact Analysis
The impact of this change on WebView2Mac is mainly reflected in improved compatibility and stability of immersive fullscreen-related window behaviors. WebView2Mac downstream code heavily relies on remote_cocoa’s window bridging and immersive mode mechanisms, and often inherits or reuses classes such as NativeWidgetNSWindowBridge and ImmersiveModeControllerCocoa. This change:
1. Removes the kFullscreenPermanentThinController feature flag and instead directly uses the macOS version for determination, simplifying downstream adaptation logic so downstream no longer needs to care about the state of this feature flag.
2. For macOS 13+, the thin controller always exists, which helps avoid UI issues (such as the toolbar not auto-hiding, black borders, etc.) caused by improper timing of titlebar accessory view controller insertion during fullscreen switching in PWA/WebView2Mac.
3. For macOS 12 and below, the original dynamic plug/unplug logic is retained to ensure compatibility.
4. As the creation and management logic of the thin controller has been adjusted, downstream code with custom titlebar accessory view controller management must ensure compatibility with the new logic, especially regarding the lifecycle and visibility of the thin controller in macOS 13+ environments.
5. This change does not affect Mojo interfaces or the signatures or behaviors of core base classes, so the impact on WebView2Mac API compatibility is minimal. However, it is recommended that downstream focus testing on immersive fullscreen and toolbar auto-hide window behaviors in macOS 13+ environments.
1. Removes the kFullscreenPermanentThinController feature flag and instead directly uses the macOS version for determination, simplifying downstream adaptation logic so downstream no longer needs to care about the state of this feature flag.
2. For macOS 13+, the thin controller always exists, which helps avoid UI issues (such as the toolbar not auto-hiding, black borders, etc.) caused by improper timing of titlebar accessory view controller insertion during fullscreen switching in PWA/WebView2Mac.
3. For macOS 12 and below, the original dynamic plug/unplug logic is retained to ensure compatibility.
4. As the creation and management logic of the thin controller has been adjusted, downstream code with custom titlebar accessory view controller management must ensure compatibility with the new logic, especially regarding the lifecycle and visibility of the thin controller in macOS 13+ environments.
5. This change does not affect Mojo interfaces or the signatures or behaviors of core base classes, so the impact on WebView2Mac API compatibility is minimal. However, it is recommended that downstream focus testing on immersive fullscreen and toolbar auto-hide window behaviors in macOS 13+ environments.
Impacted Classes:
remote_cocoa::ImmersiveModeControllerCocoa
BrowserNativeWidgetWindow (Objective-C)
NSTitlebarAccessoryViewController (使用方式变更)
remote_cocoa::features（kFullscreenPermanentThinController 已移除）