[Windows] - Fix InputTransparent layouts losing background color visibility

[prakashKannanSf3972]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Root Cause

On Windows, a LayoutPanel with InputTransparent=true and a non-null background loses its visible background color. This happens because making a Panel invisible to input requires its Background to be null in WinUI — but a null background is also visually transparent, so the color disappears. The original workaround for this inserted a non-hit-testable Canvas at index 0 of CachedChildren to serve as the visible background layer. Inserting at index 0 shifted all real logical child indexes, causing misalignment in the layout handler's child management and disrupting layout rendering.

Description of Change

This fix retains the non-hit-testable background layer concept but eliminates the child index misalignment:

• Background layer appended, not inserted: The background Canvas is now added via CachedChildren.Add() instead of CachedChildren.Insert(0, ...), so real layout children retain their correct logical indexes.

• Z-order enforced via Canvas.ZIndex: Canvas.SetZIndex(_backgroundLayer, int.MinValue) ensures the background layer always renders visually behind all real children without occupying a logical slot at the front.

• Explicit layout in ArrangeOverride: The background layer is explicitly measured and arranged to fill the full panel bounds on every layout pass, so the background remains fully visible.

Issues Fixed

Fixes #17389

Tested the behaviour in the following platforms

• Android
• Windows
• iOS
• Mac

Before	After

[dotnet-policy-service]

Hey there @@prakashKannanSf3972! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[jsuarezruiz]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 3 pipeline(s).

[jsuarezruiz]

/azp run MAUI-UITests-public

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Copilot]

Pull Request Overview

This PR refactors Windows layout input transparency handling by removing the old Canvas-based workaround, leveraging native IsHitTestVisible for hit testing, and streamlining background rendering. It also cleans up the public API surface and adds UI tests to verify the fix.

• Remove legacy UpdateInputTransparent methods from public API and LayoutPanel
• Introduce UpdatePlatformViewBackground and an internal UpdateInputTransparent in ViewExtensions
• Update the handler mapper and add end-to-end UI tests for issue 17389

Reviewed Changes

Copilot reviewed 7 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Core/src/PublicAPI/net-windows/PublicAPI.Unshipped.txt	Removed two legacy UpdateInputTransparent API entries
src/Core/src/PublicAPI/net-windows/PublicAPI.Shipped.txt	Removed shipped signatures for the removed methods
src/Core/src/Platform/Windows/ViewExtensions.cs	Added new background/update logic and internal input-transparent updater
src/Core/src/Platform/Windows/LayoutPanel.cs	Deleted legacy canvas-layer hack and related methods
src/Core/src/Handlers/Layout/LayoutHandler.Windows.cs	Mapper now calls the new internal UpdateInputTransparent
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue17389.cs	Added shared UITest for validating the Windows fix
src/Controls/tests/TestCases.HostApp/Issues/Issue17389.cs	Added host app page to drive the new UITest

Comments suppressed due to low confidence (1)

src/Core/src/PublicAPI/net-windows/PublicAPI.Shipped.txt:1649

• Removing this public API method is a breaking change; please confirm that this removal is acceptable in a minor release or bump the major version accordingly.

Microsoft.Maui.Platform.LayoutPanel.LayoutPanel() -> void

[jsuarezruiz]

/azp run MAUI-UITests-public

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[jsuarezruiz]

/rebase

[kubaflo]

Could you resolve conflicts, also we should not modify the .Shipped.txt files :)

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 30311

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 30311"

[kubaflo]

/review -b feature/refactor-copilot-yml

[kubaflo]

/review -b feature/enhanced-reviewer -p windows

[kubaflo]

Could you please check why the test is failing?

[Dhivya-SF4094]

Reviewed the AI summary and addressed the valid concern.

[vishnumenon2684]

/azp run maui-pr-uitests , maui-pr-devicetests

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).

[MauiBot]

AI Review Summary

@prakashKannanSf3972 — new AI review results are available based on this last commit: 05ecc45. To request a fresh review after new comments or commits, comment /review rerun.

---

🗂️ Review Sessions — click to expand

🚦 Gate — Test Before & After Fix

Gate Result: ✅ PASSED

Platform: WINDOWS · Base: main · Merge base: f8099fb7

Test	Without Fix (expect FAIL)	With Fix (expect PASS)
🖥️ Issue17389 Issue17389	✅ FAIL — 614s	✅ PASS — 460s

🔴 Without fix — 🖥️ Issue17389: FAIL ✅ · 614s

Error-relevant lines (filtered from the build log):

     at UITest.Appium.HelperExtensions.Wait(Func`1 query, Func`2 satisfactory, String timeoutMessage, Nullable`1 timeout, Nullable`1 retryFrequency) in /_/src/TestUtils/src/UITest.Appium/HelperExtensions.cs:line 2757
   at UITest.Appium.HelperExtensions.WaitForAtLeastOne(Func`1 query, String timeoutMessage, Nullable`1 timeout, Nullable`1 retryFrequency) in /_/src/TestUtils/src/UITest.Appium/HelperExtensions.cs:line 2784
   at UITest.Appium.HelperExtensions.WaitForElement(IApp app, String marked, String timeoutMessage, Nullable`1 timeout, Nullable`1 retryFrequency, Nullable`1 postTimeout) in /_/src/TestUtils/src/UITest.Appium/HelperExtensions.cs:line 793
   at Microsoft.Maui.TestCases.Tests.Issues.Issue17389.ValidateBackgroundColorDoesNotAffectInputTransparent() in /_/src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue17389.cs:line 19
   at System.Reflection.MethodBaseInvoker.InterpretedInvoke_Method(Object obj, IntPtr* args)
   at System.Reflection.MethodBaseInvoker.InvokeWithNoArgs(Object obj, BindingFlags invokeAttr)
   at Microsoft.Maui.TestCases.Tests.Issues.Issue17389.ValidateInputTransparentBackgroundColorToggle() in /_/src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue17389.cs:line 51

🟢 With fix — 🖥️ Issue17389: PASS ✅ · 460s

(no coded error found; showing last 1200 chars)

.0\Controls.TestCases.WinUI.Tests.dll
   NUnit3TestExecutor discovered 2 of 2 NUnit test cases using Current Discovery mode, Non-Explicit run
>>>>> 7/16/2026 2:57:33 PM FixtureSetup for Issue17389(Windows)
>>>>> 7/16/2026 2:57:42 PM ValidateBackgroundColorDoesNotAffectInputTransparent Start
>>>>> 7/16/2026 2:57:51 PM ValidateBackgroundColorDoesNotAffectInputTransparent Stop
  Passed ValidateBackgroundColorDoesNotAffectInputTransparent [9 s]
>>>>> 7/16/2026 2:57:51 PM ValidateInputTransparentBackgroundColorToggle Start
>>>>> 7/16/2026 2:57:53 PM ValidateInputTransparentBackgroundColorToggle Stop
  Passed ValidateInputTransparentBackgroundColorToggle [1 s]
NUnit Adapter 4.5.0.0: Test execution complete
[xUnit.net 00:00:00.00] xUnit.net VSTest Adapter v2.8.2+699d445a1a (64-bit .NET 10.0.0)
[xUnit.net 00:00:00.11]   Discovering: Controls.TestCases.WinUI.Tests
[xUnit.net 00:00:00.32]   Discovered:  Controls.TestCases.WinUI.Tests
Results File: D:\a\1\s\CustomAgentLogsTmp\UITests\TestResults\Issue17389.trx

Test Run Successful.
Total tests: 2
     Passed: 2
 Total time: 34.6804 Seconds
>>> TRX_RESULT_FILE: D:\a\1\s\CustomAgentLogsTmp\UITests\TestResults\Issue17389.trx

📁 Fix files reverted (2 files)

• src/Core/src/Platform/Windows/LayoutPanel.cs
• src/Core/src/Platform/Windows/ViewExtensions.cs

---

📱 UI Tests — Layout,ViewBaseTests

Detected UI test categories: Layout,ViewBaseTests

✅ Deep UI tests — 308 passed, 0 failed across 2 categories on platform-pool agent (replaces in-process counts above).

🧪 UI Test Execution Results (deep, platform pool)

Category	Tests	Snapshot diffs
Layout	193/197 ✓	—
ViewBaseTests	115/115 ✓	—
📎 Download drop-deep-uitests artifact (TRX + snapshot diffs)

---

📋 Pre-Flight — Context & Validation

Issue: #17389 - InputTransparent should not affect background color on Windows layouts
PR: #30311 - Windows LayoutPanel InputTransparent background/index fix
Platforms Affected: Windows
Files Changed: 2 implementation, 10 test/snapshot

Key Findings

• GitHub CLI is unauthenticated in this environment, so full PR/issue comments could not be fetched; local checked-out PR diff and code-review output were used.
• The PR changes LayoutPanel to append the background canvas and force it behind children with Canvas.ZIndex=int.MinValue, avoiding the original index-shift caused by inserting the background layer at child index 0.
• The supplied gate result says tests already fail without the fix and pass with the PR fix; gate verification was not rerun.
• Impacted UI test category: Layout.

Code Review Summary

Verdict: NEEDS_DISCUSSION
Confidence: low
Errors: 0 | Warnings: 2 | Suggestions: 0

Key code review findings:

• ⚠ src/Core/src/Platform/Windows/LayoutPanel.cs:102 — background layer appended with Canvas.ZIndex=int.MinValue can tie with a real child using the same minimum ZIndex.
• ⚠ src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue17389.cs:52 — screenshot test captures before toggling InputTransparent, so it does not directly exercise _backgroundLayer rendering.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #30311	Append background layer to avoid logical child index shift; force layer behind children with Canvas.ZIndex=int.MinValue; arrange layer to panel bounds.	✅ PASSED (Gate, supplied)	LayoutPanel.cs, ViewExtensions.cs, UI tests/snapshots	Original PR

---

🔬 Code Review — Deep Analysis

Code Review — PR #30311

Independent Assessment

What this changes: Windows LayoutPanel keeps the existing non-hit-testable background Canvas workaround for InputTransparent=true layouts, but appends the canvas instead of inserting at child index 0. It then pushes that canvas behind normal children with Canvas.ZIndex=int.MinValue and explicitly arranges it to fill the panel.

Inferred motivation: Avoid shifting MAUI logical child indexes in LayoutHandler.Windows.cs, while preserving visible backgrounds for input-transparent layouts.

Reconciliation with PR Narrative

Author claims: The PR fixes #17389 by appending the background layer, enforcing z-order, and arranging it to panel bounds.
Agreement/disagreement: This matches the code. The child-index issue is addressed. Edge-case risk remains in z-order tie behavior and screenshot coverage does not exercise the fixed background-layer path before toggling colors.

Prior Review Reconciliation

Prior ❌ Error Finding	Source	Status	Evidence
Setting LayoutPanel.IsHitTestVisible=false breaks child hit testing	MauiBot inline reviews	✅ Fixed	Current ViewExtensions.UpdateInputTransparent(this LayoutPanel...) is a noop; background handling routes through UpdatePlatformViewBackground and LayoutPanel.UpdateInputTransparent.
Removing shipped Windows public APIs is a breaking change	MauiBot / kubaflo	✅ Fixed	Current diff no longer changes PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt.
Test metadata pointed at issue 21331 instead of 17389	MauiBot	✅ Fixed	Current [Issue(..., 17389, ...)] is correct.
Windows screenshot baselines missing	MauiBot	✅ Fixed	Current diff includes Windows screenshot baselines.

Blast Radius Assessment

• Runs for all instances: No, only Windows LayoutPanel instances with InputTransparent=true and non-null background get the extra background layer.
• Startup impact: No direct startup path; runs during layout/background/input-transparent updates and arrange.
• Static/shared state: No.

CI Status

• Required-check result: gh pr checks --required unavailable (gh auth login required). Prior gate result supplied by caller: Gate ✅ PASSED — tests FAIL without fix, PASS with fix.
• Classification: undetermined for broader required checks; gate is already validated by caller.
• Action taken: confidence capped low for broader CI; gate was not rerun per instruction.

Findings

⚠️ Warning — Background layer can render above a real child with ZIndex=int.MinValue

src/Core/src/Platform/Windows/LayoutPanel.cs:102

The new background layer gets Canvas.ZIndex=int.MinValue and is appended to CachedChildren. If an app sets a real child’s MAUI ZIndex to int.MinValue, both elements tie at the WinUI z-index level. Since the background layer is appended after real children, WinUI tie-breaking can draw it above that child, visually covering it while still being non-hit-testable.

⚠️ Warning — Screenshot test does not exercise the fixed background-layer path

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue17389.cs:52

ValidateInputTransparentBackgroundColorToggle screenshots before toggling InputTransparent, so controls remain InputTransparent=false and use normal WinUI backgrounds rather than the LayoutPanel _backgroundLayer path this PR changes.

Failure-Mode Probing

• Child index management: Appending avoids shifting LayoutHandler child indexes; Add/Insert/Update can still target logical children correctly.
• Disconnect/reconnect: CachedChildren.Clear() may leave _backgroundLayer non-null but detached; current PR re-adds it because Contains is false.
• Null/default background: background == null removes the layer for transparent layouts; visible layouts get a transparent brush to preserve hit testing.
• Equal minimum z-index: A real child at int.MinValue can tie with the appended canvas and be painted underneath it.

Verdict: NEEDS_DISCUSSION

Confidence: low
Summary: The main approach is directionally sound and prior major findings appear addressed, but the z-order edge case and test coverage gap are relevant to alternative fix exploration. Broader CI is unavailable in this environment.

---

📝 Recommended PR Title & Description

Assessment: ✏️ Recommend updating — the current description accurately explains the raw PR fix, but the winning fix includes reviewer-driven lifecycle and test coverage corrections that are not reflected yet.

Recommended title

[Windows] LayoutPanel: Preserve InputTransparent background layer visibility

Recommended description

### Root Cause

On Windows, a `LayoutPanel` with `InputTransparent=true` and a non-null background loses its visible background color. Making a WinUI `Panel` invisible to input requires its `Background` to be null, but a null background is also visually transparent.

The existing workaround inserted a non-hit-testable `Canvas` at index 0 of `CachedChildren` to serve as the visible background layer. Inserting that private layer before real children shifted logical child indexes and could disrupt layout child management/rendering. Additionally, when a layout is initialized with `InputTransparent=true` and a background, `LayoutHandler.SetVirtualView` can clear and rebuild `CachedChildren` after the background layer is created, so the private layer must be preserved or reinserted after that rebuild.

### Description of Change

- **Background layer appended, not inserted**: The background `Canvas` is added without shifting real layout children away from their logical indexes.
- **Z-order enforced via `Canvas.ZIndex`**: The private background layer is kept visually behind real children.
- **Explicit layout in `ArrangeOverride`**: The background layer is measured and arranged to fill the full panel bounds on each layout pass.
- **Initial-state lifecycle handled**: Rebuild paths preserve/reapply the background layer for layouts that start with `InputTransparent=true` and a non-null background.
- **Regression coverage improved**: The Issue17389 UI test covers the `InputTransparent=true` visual background-layer path, not just normal `Panel.Background` rendering.

### Issues Fixed

Fixes #17389

**Tested the behaviour in the following platforms**

- [ ] Android
- [x] Windows
- [ ] iOS
- [ ] Mac

| Before | After |
|--|--|
| <img src="https://github.com/user-attachments/assets/4534d12d-d85e-4cfe-8912-55e029c2cad1"> | <img src="https://github.com/user-attachments/assets/1943aec4-def9-4f2a-a627-19170c23176a"> |

---

🏁 Report — Final Recommendation

Comparative Fix Report — PR #30311

Candidates compared

Candidate	Approach	Regression result	Review result	Rank
pr-plus-reviewer	Raw PR appended background layer plus reviewer feedback: preserve/reinsert the layer after SetVirtualView child rebuild and extend screenshots to cover InputTransparent=true.	Expected pass, based on raw PR gate plus targeted lifecycle correction	Addresses all expert findings	1
try-fix-1	Keep the background layer inserted at visual index 0 and offset Windows layout-handler logical indexes when the private layer is present.	Passed targeted Issue17389 UI tests	Still vulnerable to initial InputTransparent=true background layer removal after SetVirtualView clears children	2
pr	Append background layer, force it behind children with native Canvas.ZIndex=int.MinValue, and explicitly arrange it to panel bounds.	Passed supplied gate: tests fail without fix and pass with fix	Has a major initial-state lifecycle gap and incomplete visual regression coverage	3

Analysis

The raw PR fixes the original index-shift symptom for the exercised toggle path by no longer inserting the private background layer before real children. The supplied gate is strong evidence for the reported repro: without the fix Issue17389 fails, and with the PR fix both Issue17389 UI tests pass.

However, the expert reviewer identified a major lifecycle issue in the raw PR: when a layout starts with InputTransparent=true and a non-null background, mapper execution can create the background layer before LayoutHandler.SetVirtualView clears CachedChildren. The clear removes the layer, _backgroundLayer remains non-null, and no subsequent remap is guaranteed. That makes raw pr lower quality than candidates that preserve the layer after child rebuild. The reviewer also identified a test gap: the screenshot test should capture the InputTransparent=true visual state, not only the normal background path.

try-fix-1 passed the same targeted UI tests and avoids the native Canvas.ZIndex tie concern by keeping the private background layer structurally at index 0 while offsetting handler child indexes. But it inherits the same initial-state lifecycle weakness because it also depends on the layer being present in CachedChildren after SetVirtualView clears and rebuilds children. Its additional handler-index translation also broadens the implementation surface compared with the PR's localized platform-panel fix.

pr-plus-reviewer is the winning candidate. It preserves the raw PR's passing behavior and lower implementation surface while applying the expert review's concrete corrections. No candidate failed the supplied regression tests; among passing candidates, pr-plus-reviewer best covers both the reported repro and the discovered initial-state edge case.

Winner

pr-plus-reviewer

---

🧭 Next Steps — review latest findings

No alternative fix was selected for this run. Review the session findings and CI results before merging.

[MauiBot]

Expert Review — 2 findings

See inline comments for details.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[moderate] Regression Prevention and Test Coverage — This baseline screenshot is captured before the test enables InputTransparent, so the visual assertions exercise the normal LayoutPanel.Background path rather than the Windows background-layer path changed by this PR. A regression in the added layer sizing/z-order would not be caught here; take at least one screenshot after toggling InputTransparent while the layouts still have non-null backgrounds.