[iOS] Fix SafeArea infinite layout cycle with parent hierarchy walk and pixel-level comparison (dotnet#34024)

<!-- Please let the below note in for people that find this PR -->
> [!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](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from
this PR and let us know in a comment if this change resolves your issue.
Thank you!

### Root Cause

`SafeAreaInsetsDidChange` fires repeatedly during iOS animations (e.g.,
`TranslateToAsync`, bottom sheet transitions) as views move relative to
the window. This caused two distinct infinite loop patterns:

1. **Sub-pixel oscillation** (dotnet#32586, dotnet#33934): Animations produce
sub-pixel differences in `SafeAreaInsets` (e.g., `0.0000001pt`). Exact
equality fails, triggering `InvalidateAncestorsMeasures` → layout pass →
position change → new `SafeAreaInsetsDidChange` → infinite loop.

2. **Parent-child double application** (dotnet#33595): A `ContentPage`
(implementing `ISafeAreaView`) and its child `Grid` both independently
apply safe area adjustments. When the `ContentPage` adjusts its layout
for the notch/status bar, it repositions the `Grid`. The `Grid`'s new
position fires `SafeAreaInsetsDidChange`, causing it to re-apply its own
adjustment — creating a ping-pong loop.

### Description of Change

**Primary fix — `IsParentHandlingSafeArea` (parent hierarchy walk):**

In both `MauiView.ValidateSafeArea` and
`MauiScrollView.ValidateSafeArea`, before applying safe area
adjustments, we now check whether an ancestor `MauiView` is already
applying safe area for the **same edges**. If so, the child skips its
own adjustment to avoid double-padding.

The check is **edge-aware**: a parent handling `Top` does not block a
child from independently handling `Bottom`. Only overlapping edges cause
deferral. The `_parentHandlesSafeArea` result is cached per layout cycle
and cleared on `SafeAreaInsetsDidChange`, `InvalidateSafeArea`, and
`MovedToWindow`.

**Secondary fix — `EqualsAtPixelLevel`:**

Safe area values are compared at device-pixel resolution (rounding to `1
/ ContentScaleFactor`) before deciding whether to trigger a layout
invalidation. This absorbs sub-pixel animation noise and prevents the
oscillation loops in dotnet#32586 and dotnet#33934.

**MauiScrollView bug fixes:**
- Inverted condition: `!UpdateContentInsetAdjustmentBehavior()` was
incorrectly gating behavior; corrected to
`UpdateContentInsetAdjustmentBehavior()`.
- The `_appliesSafeAreaAdjustments` flag now correctly incorporates
`!IsParentHandlingSafeArea()`.

**What was removed:**
- The "Window Guard" approach (comparing `Window.SafeAreaInsets` to
filter noise) was tried and removed. It was fragile: on macCatalyst with
a custom TitleBar, `WindowViewController` repositions content by pushing
it down, which changes the view's own `SafeAreaInsets` without changing
`Window.SafeAreaInsets`. The guard blocked this legitimate change,
causing a 28px content shift regression in CI.

### Issues Fixed
Fixes dotnet#32586
Fixes dotnet#33934
Fixes dotnet#33595
Fixes dotnet#34042

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Tamilarasan-Paranthaman <Tamilarasan-Paranthaman@users.noreply.github.com>

Author: 4 people

.github/copilot-instructions.md

@@ -201,10 +201,17 @@ git commit -m "Fix: Description of the change"
 2. Exception: If the user's instructions explicitly include pushing, proceed without asking.
 
 ### Documentation
+
 - Update XML documentation for public APIs
 - Follow existing code documentation patterns
 - Update relevant docs in `docs/` folder when needed
 
+**Platform-Specific Documentation:**
+- `.github/instructions/safe-area-ios.instructions.md` - Safe area investigation (iOS/macCatalyst)
+- `.github/instructions/uitests.instructions.md` - UI test guidelines (includes safe area testing section)
+- `.github/instructions/android.instructions.md` - Android handler implementation
+- `.github/instructions/xaml-unittests.instructions.md` - XAML unit test guidelines
+
 ### Opening PRs
 
 All PRs are required to have this at the top of the description:

.github/instructions/safe-area-ios.instructions.md

@@ -0,0 +1,34 @@
+---
+applyTo:
+  - "**/Platform/iOS/MauiView.cs"
+  - "**/Platform/iOS/MauiScrollView.cs"
+  - "**/Platform/iOS/*SafeArea*"
+---
+
+# Safe Area Guidelines (iOS/macCatalyst)
+
+## Platform Differences
+
+| | macOS 14/15 | macOS 26+ |
+|-|-------------|-----------|
+| Title bar inset | ~28px | ~0px |
+| Used in CI | ✅ | ❌ |
+
+Local macOS 26+ testing does NOT validate CI behavior. Fixes must pass CI on macOS 14/15.
+
+| Platform | `UseSafeArea` default |
+|----------|-----------------------|
+| iOS | `false` |
+| macCatalyst | `true` |
+
+## Architecture (PR #34024)
+
+**`IsParentHandlingSafeArea`** — before applying adjustments, `MauiView`/`MauiScrollView` walk ancestors to check if any ancestor handles the **same edges**. If so, descendant skips (avoids double-padding). Edge-aware: parent handling `Top` does not block child handling `Bottom`. Result cached in `bool? _parentHandlesSafeArea`; cleared on `SafeAreaInsetsDidChange`, `InvalidateSafeArea`, `MovedToWindow`. `AppliesSafeAreaAdjustments` is `internal` for cross-type ancestor checks.
+
+**`EqualsAtPixelLevel`** — safe area compared at device-pixel resolution to absorb sub-pixel animation noise (`0.0000001pt` during `TranslateToAsync`), preventing oscillation loops (#32586, #33934).
+
+## Anti-Patterns
+
+**❌ Window Guard** — comparing `Window.SafeAreaInsets` to filter callbacks blocks legitimate updates. On macCatalyst + custom TitleBar, `WindowViewController` pushes content down, changing the **view's** `SafeAreaInsets` without changing the **window's**. Caused 28px CI shift (macOS 14/15 only). Never gate per-view callbacks on window-level insets.
+
+**❌ Semantic mismatch** — `_safeArea` is filtered by `GetSafeAreaForEdge` (zeroes edges per `SafeAreaRegions`); raw `UIView.SafeAreaInsets` includes all edges. Never compare them — compare raw-to-raw or adjusted-to-adjusted.

.github/instructions/uitests.instructions.md

@@ -731,3 +731,45 @@ grep -r "UITestEntry\|UITestEditor\|UITestSearchBar" src/Controls/tests/TestCase
 - Common helper methods
 - Platform-specific workarounds
 - UITest optimized control usage
+
+### Safe Area Testing (iOS/MacCatalyst)
+
+**⚠️ CRITICAL for macCatalyst safe area tests:**
+
+Safe area behavior differs significantly between macOS versions. Tests must account for this variability.
+
+| macOS Version | Title Bar Safe Area | CI Environment |
+|---------------|---------------------|----------------|
+| **macOS 14/15** | ~28px top inset | ✅ Used by CI |
+| **macOS 26 (Liquid Glass)** | ~0px top inset | ❌ Local dev only |
+
+**Rules for safe area tests:**
+
+1. **Use tolerances for safe area measurements** - Exact pixel values vary by macOS version
+2. **Test behavior, not exact values** - Verify content is NOT obscured, rather than checking exact padding pixels
+3. **Use `GetRect()` for child content position** - Measure where content actually appears, not parent size
+4. **Never hardcode safe area expectations** - Tests should pass on macOS 14/15 AND macOS 26
+
+**Example patterns:**
+
+```csharp
+// ❌ BAD: Hardcoded safe area value (breaks across macOS versions)
+var safeArea = element.GetRect();
+Assert.That(safeArea.Y, Is.EqualTo(28)); // Fails on macOS 26
+
+// ✅ GOOD: Test that content is not obscured by title bar
+var contentRect = App.WaitForElement("MyContent").GetRect();
+var titleBarRect = App.WaitForElement("TitleBar").GetRect();
+Assert.That(contentRect.Y, Is.GreaterThanOrEqualTo(titleBarRect.Height), 
+    "Content should not be obscured by title bar");
+
+// ✅ GOOD: Use tolerance for safe area (accounts for OS differences)
+Assert.That(contentRect.Y, Is.GreaterThan(0).And.LessThan(50), 
+    "Content should have some top padding but not excessive");
+```
+
+**Test category**: Use `UITestCategories.SafeAreaEdges` for safe area tests.
+
+**Platform scope**: Safe area tests should typically run on iOS and MacCatalyst (not just one).
+
+**See also**: `.github/instructions/safe-area-debugging.instructions.md` for investigation guidelines

src/Controls/tests/TestCases.HostApp/Issues/Issue28986_ParentChildTest.xaml

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+             x:Class="Maui.Controls.Sample.Issues.Issue28986_ParentChildTest"
+             Title="Issue28986 - Parent Child SafeArea">
+
+    <Grid x:Name="ParentGrid"
+          BackgroundColor="#FFEB3B"
+          SafeAreaEdges="None,Container,None,None"
+          AutomationId="ParentGrid">
+
+        <Grid.RowDefinitions>
+            <RowDefinition Height="Auto"/>
+            <RowDefinition Height="*"/>
+            <RowDefinition Height="Auto"/>
+        </Grid.RowDefinitions>
+
+        <!-- Top Indicator -->
+        <Label Grid.Row="0"
+               Text="↑ Parent handles TOP safe area ↑"
+               BackgroundColor="#FF5722"
+               TextColor="White"
+               HorizontalTextAlignment="Center"
+               AutomationId="TopIndicator"/>
+
+        <!-- Middle Content Area -->
+        <VerticalStackLayout Grid.Row="1"
+                             BackgroundColor="#00BCD4"
+                             VerticalOptions="Center"
+                             Spacing="20"
+                             Padding="20">
+
+            <Label Text="SafeAreaEdges Independent Handling Demo"
+                   FontSize="20"
+                   FontAttributes="Bold"
+                   HorizontalTextAlignment="Center"
+                   AutomationId="TitleLabel"/>
+
+            <Label x:Name="StatusLabel"
+                   Text="Parent: Top=Container, Bottom=None | Child: Bottom=Container"
+                   HorizontalTextAlignment="Center"
+                   AutomationId="StatusLabel"/>
+
+            <Button Text="Toggle Parent Top SafeArea"
+                    Clicked="OnToggleParentTop"
+                    HorizontalOptions="Center"
+                    AutomationId="ToggleParentTopButton"/>
+
+            <Button Text="Toggle Parent Bottom SafeArea"
+                    Clicked="OnToggleParentBottom"
+                    HorizontalOptions="Center"
+                    AutomationId="ToggleParentBottomButton"/>
+
+            <Button Text="Toggle Child Bottom SafeArea"
+                    Clicked="OnToggleChildBottom"
+                    HorizontalOptions="Center"
+                    AutomationId="ToggleChildBottomButton"/>
+
+            <Label Text="Expected behavior:"
+                   FontAttributes="Bold"
+                   Margin="0,20,0,0"
+                   AutomationId="ExpectedLabel"/>
+
+            <Label Text="• Top indicator stays below notch/status bar (parent handles top)&#x0a;• Bottom indicator stays above home indicator (child handles bottom)&#x0a;• Both work INDEPENDENTLY - no conflict!&#x0a;• Runtime changes to parent do NOT disrupt child's handling&#x0a;• NO DOUBLE PADDING when both parent and child handle same edge"
+                   FontSize="12"
+                   AutomationId="ExpectedDetailsLabel"/>
+
+        </VerticalStackLayout>
+
+        <!-- Bottom Indicator -->
+        <Grid Grid.Row="2"
+              BackgroundColor="#9C27B0"
+              x:Name="ChildGrid"
+              SafeAreaEdges="None,None,None,Container"
+              AutomationId="ChildGrid">
+
+            <Label Text="↓ Child handles BOTTOM safe area ↓"
+                   BackgroundColor="#8BC34A"
+                   HorizontalTextAlignment="Center"
+                   AutomationId="BottomIndicator"/>
+
+        </Grid>
+    </Grid>
+</ContentPage>

src/Controls/tests/TestCases.HostApp/Issues/Issue28986_ParentChildTest.xaml.cs

@@ -0,0 +1,59 @@
+namespace Maui.Controls.Sample.Issues;
+
+[Issue(IssueTracker.Github, 28986, "SafeAreaEdges independent handling for parent and child controls", PlatformAffected.iOS, issueTestNumber: 9)]
+public partial class Issue28986_ParentChildTest : ContentPage
+{
+    bool _parentTopEnabled = true;
+    bool _parentBottomEnabled = false;
+    bool _childBottomEnabled = true;
+
+    public Issue28986_ParentChildTest()
+    {
+        InitializeComponent();
+        UpdateParentGridSafeAreaEdges();
+        UpdateStatusLabel();
+    }
+
+    void OnToggleParentTop(object sender, EventArgs e)
+    {
+        _parentTopEnabled = !_parentTopEnabled;
+        UpdateParentGridSafeAreaEdges();
+        UpdateStatusLabel();
+    }
+
+    void OnToggleParentBottom(object sender, EventArgs e)
+    {
+        _parentBottomEnabled = !_parentBottomEnabled;
+        UpdateParentGridSafeAreaEdges();
+        UpdateStatusLabel();
+    }
+
+    void OnToggleChildBottom(object sender, EventArgs e)
+    {
+        _childBottomEnabled = !_childBottomEnabled;
+
+        // Toggle between Bottom=Container and Bottom=None
+        ChildGrid.SafeAreaEdges = _childBottomEnabled
+            ? new SafeAreaEdges(SafeAreaRegions.None, SafeAreaRegions.None, SafeAreaRegions.None, SafeAreaRegions.Container)
+            : new SafeAreaEdges(SafeAreaRegions.None);
+
+        UpdateStatusLabel();
+    }
+
+    void UpdateParentGridSafeAreaEdges()
+    {
+        // Build parent grid SafeAreaEdges based on top and bottom flags
+        SafeAreaRegions top = _parentTopEnabled ? SafeAreaRegions.Container : SafeAreaRegions.None;
+        SafeAreaRegions bottom = _parentBottomEnabled ? SafeAreaRegions.Container : SafeAreaRegions.None;
+
+        ParentGrid.SafeAreaEdges = new SafeAreaEdges(SafeAreaRegions.None, top, SafeAreaRegions.None, bottom);
+    }
+
+    void UpdateStatusLabel()
+    {
+        var parentTop = _parentTopEnabled ? "Container" : "None";
+        var parentBottom = _parentBottomEnabled ? "Container" : "None";
+        var childBottom = _childBottomEnabled ? "Container" : "None";
+        StatusLabel.Text = $"Parent: Top={parentTop}, Bottom={parentBottom} | Child: Bottom={childBottom}";
+    }
+}