Issue: #34518 - WebView background color has changed after update, can't override
PR: #34599 - [Windows] Fix WebView background color not being applied
Platforms Affected: Windows (primary); snapshot baselines added for Android, iOS, iOS-26, Mac, Windows
Files Changed: 3 implementation (WebViewHandler.Windows.cs, WebViewHandler.cs, WebViewExtensions.cs), 7 test/snapshot files

Key Findings

• Root bug (Issue WebView background color has changed after update, can't override. #34518): On Windows, WebView2 in dark mode shows a black background and BackgroundColor="White" can't override it. WebViewHandler had no property mapper for Background on Windows.
• PR fix: Adds [nameof(IView.Background)] = MapBackground (Windows-only #if WINDOWS) to WebViewHandler.cs, implements internal static void MapBackground in WebViewHandler.Windows.cs, and adds UpdateBackground extension in WebViewExtensions.cs.
• UpdateBackground behavior: Sets WebView2.DefaultBackgroundColor from SolidPaint or GradientPaint.StartColor. Forces PreferredColorScheme.Light when any background is set; resets to Auto when background is null.
• PreferredColorScheme.Light always forced (🚨 critical): Regardless of whether the set color is dark or light, the code forces Light color scheme. A dark BackgroundColor (e.g., Colors.Black) would still force Light scheme for web content, breaking prefers-color-scheme: dark media queries. Author's rationale: choosing Dark makes WebView2's dark-mode rendering override DefaultBackgroundColor. This argument applies only when a LIGHT background is set; forcing Light for ALL colors is overly broad.
• DefaultBackgroundColor not reset in else branch (⚠️ correctness bug): Prior reviewer suggested adding platformWebView.DefaultBackgroundColor = Colors.Transparent.ToWindowsColor() in the else branch; author responded "I have updated the suggestion" but the code on disk still lacks this reset. The thread was marked outdated (possibly due to a new commit that didn't fully apply the fix).
• TODO: Make it public in .NET 11. comment: No tracking issue/link. Thread resolved without fix applied.
• PlatformAffected.UWP in test: Should be PlatformAffected.Windows for .NET MAUI on Windows.
• Snapshots: All 4 platform baselines now present (Android, Mac, WinUI, iOS, iOS-26) — this was missing in the prior review and is now fixed.
• Prior agent review (same PR, 2026-03-27): Gate failed at that time; agent ran 4 try-fix attempts (all passing); recommended REQUEST CHANGES. Gate now ✅ PASSED after snapshot updates.
• iOS already has MapBackground: WebViewHandler.cs line 37 has [nameof(IWebView.Background)] = MapBackground for iOS — the Windows addition is correctly guarded with #if WINDOWS.

Fix Candidates

Fix Candidates

Cross-Pollination

Exhausted: Yes
Selected Fix: Attempt 2 (DefaultBackgroundColor-only + transparent reset) — Simplest minimal change; removes the forced PreferredColorScheme.Light side-effect entirely; adds missing DefaultBackgroundColor reset; leaves web content prefers-color-scheme media queries unaffected. The PR author should adopt this approach in WebViewExtensions.cs.

⚠️ Final Recommendation: REQUEST CHANGES

Phase Status

Summary

PR #34599 correctly identifies the root cause and adds the right infrastructure (MapBackground + UpdateBackground using WebView2.DefaultBackgroundColor) to fix Windows WebView background color. The Gate passes. However, the UpdateBackground implementation has a correctness issue (PreferredColorScheme.Light forced for all background colors) and a missing reset (DefaultBackgroundColor not cleared in else branch). Four independent alternatives all pass, with the simplest (DefaultBackgroundColor-only) being the recommended fix. The PR author should update WebViewExtensions.cs before merging.

Root Cause

WebView2 does not inherit from WinUI Control, so the standard ViewHandler.MapBackground pipeline never reaches it. WebView2.DefaultBackgroundColor is the correct API to set the pre-render background. The fix correctly adds a Windows-specific IView.Background mapper to WebViewHandler.

Fix Quality

What the PR gets right:

• ✅ Correct mapper registration: [nameof(IView.Background)] = MapBackground inside #if WINDOWS
• ✅ Correct API: WebView2.DefaultBackgroundColor
• ✅ Calls UpdateBackground in OnCoreWebView2Initialized (re-applies after async WebView2 init)
• ✅ Handles both SolidPaint and GradientPaint (best-effort for gradient)
• ✅ Tests added with baseline snapshots for all 4 platforms (Android, iOS, iOS-26, Mac, Windows)
• ✅ PlatformAffected.UWP is correct — the PlatformAffected enum has no Windows member; UWP is the established convention for Windows in this codebase

Issues requiring changes:

1. PreferredColorScheme.Light always forced (🚨 correctness issue):

   // Current (PROBLEMATIC):
   platformWebView.CoreWebView2.Profile.PreferredColorScheme = CoreWebView2PreferredColorScheme.Light;
   // Forces ALL web content into Light mode whenever ANY background color is set,
   // even dark colors (Colors.Black). Web apps using `prefers-color-scheme: dark`
   // CSS media queries will have their dark-mode styles suppressed.

   Recommended fix: Remove PreferredColorScheme changes entirely (Attempt 2 approach). DefaultBackgroundColor works independently of PreferredColorScheme — the color scheme setting affects how web content renders, not whether the background color property is respected.

   // Recommended UpdateBackground in WebViewExtensions.cs:
   internal static void UpdateBackground(this WebView2 platformWebView, IWebView webView)
   {
       Color? backgroundColor = null;
       if (webView.Background is SolidPaint solidPaint)
           backgroundColor = solidPaint.Color;
       else if (webView.Background is GradientPaint gradientPaint)
           backgroundColor = gradientPaint.StartColor;
   
       platformWebView.DefaultBackgroundColor = backgroundColor is not null
           ? backgroundColor.ToWindowsColor()
           : Colors.Transparent.ToWindowsColor();
   }

2. DefaultBackgroundColor not reset in else branch (⚠️ correctness bug):
   The current else branch only resets PreferredColorScheme but leaves DefaultBackgroundColor at a stale previously-set color if the developer later clears their BackgroundColor. The recommended fix above addresses this unconditionally.

3. TODO: Make it public in .NET 11. comment without tracking issue (🔧 minor):

   //TODO: Make it public in .NET 11.
   internal static void MapBackground(IWebViewHandler handler, IWebView webView)

   Either remove this comment or replace with a linked GitHub issue. Version-targeted TODOs without tracking issues create dead-end comments.

Best Alternative Found

Attempt 2 (DefaultBackgroundColor-only, claude-sonnet-4.6): Same 3-file structure as the PR, but removes all PreferredColorScheme logic and properly resets DefaultBackgroundColor to transparent in the else branch. Minimal delta from current code, zero side-effects on CSS media queries. This is the recommended path for the PR author.

Selected Fix: Attempt 2 — simpler, more correct, and leaves web content rendering unaffected.