Done

Author: Vetle444

CHANGELOG.md

@@ -1,5 +1,5 @@
 ## [56.1.0]
-- Test
+- [LayoutDiagnostics] Added runtime layout diagnostics API for profiling measure/arrange counts per element type. Includes a floating overlay visible over modals and bottom sheets, automatic snapshot capture during page and bottom sheet lifecycle, per-instance thrashing detection, and JSON export.
 
 ## [56.0.2]
 - [iOS][ItemPicker] Fixed bug where selected item could reset randomly

src/library/DIPS.Mobile.UI/API/Diagnostics/Android/LayoutDiagnosticsService.cs

@@ -93,17 +93,9 @@ private static void AddOverlayToActivityContent()
 
     private static Android.Widget.FrameLayout.LayoutParams CreateOverlayLayoutParams()
     {
-        var activity = Platform.CurrentActivity;
-        var density = activity?.Resources?.DisplayMetrics?.Density ?? 1;
-        
         return new Android.Widget.FrameLayout.LayoutParams(
-            ViewGroup.LayoutParams.WrapContent,
-            ViewGroup.LayoutParams.WrapContent,
-            GravityFlags.Top | GravityFlags.End)
-        {
-            TopMargin = (int)(54 * density),
-            RightMargin = (int)(8 * density)
-        };
+            ViewGroup.LayoutParams.MatchParent,
+            ViewGroup.LayoutParams.MatchParent);
     }
 
     private static partial void UpdateOverlay(LayoutDiagnosticsSnapshot snapshot)

src/library/DIPS.Mobile.UI/API/Diagnostics/LayoutDiagnosticsOverlay.cs

@@ -4,8 +4,8 @@
 using DIPS.Mobile.UI.Resources.Styles;
 using DIPS.Mobile.UI.Resources.Styles.Button;
 using DIPS.Mobile.UI.Resources.Styles.Label;
+using Microsoft.Maui.Controls.Shapes;
 using Colors = DIPS.Mobile.UI.Resources.Colors.Colors;
-using LayoutEffect = DIPS.Mobile.UI.Effects.Layout.Layout;
 
 namespace DIPS.Mobile.UI.API.Diagnostics;
 
@@ -19,8 +19,8 @@ internal class LayoutDiagnosticsOverlay : Grid
     private readonly Label m_detailLabel;
     private readonly Button m_toggleButton;
     private readonly Grid m_expandedContent;
-    private readonly Grid m_collapsedPill;
-    private readonly Grid m_expandedPanel;
+    private readonly Border m_collapsedPill;
+    private readonly Border m_expandedPanel;
     private readonly Label m_collapsedCountLabel;
     private readonly BoxView m_recordingDot;
     private readonly BoxView m_expandedRecordingDot;
@@ -33,15 +33,6 @@ public LayoutDiagnosticsOverlay()
     {
         InputTransparent = false;
         CascadeInputTransparent = false;
-        
-        HorizontalOptions = LayoutOptions.End;
-        VerticalOptions = LayoutOptions.Start;
-        
-        Margin = new Thickness(
-            Sizes.GetSize(SizeName.content_margin_small),
-            54,
-            Sizes.GetSize(SizeName.content_margin_small),
-            0);
 
         // ── Collapsed pill ──
         m_recordingDot = new BoxView
@@ -70,16 +61,19 @@ public LayoutDiagnosticsOverlay()
             Children = { m_recordingDot, m_collapsedCountLabel }
         };
 
-        m_collapsedPill = new Grid
+        m_collapsedPill = new Border
         {
             BackgroundColor = Colors.GetColor(ColorName.color_surface_backdrop),
             Padding = new Thickness(
-                Sizes.GetSize(SizeName.content_margin_medium),
-                Sizes.GetSize(SizeName.content_margin_small)),
-            HorizontalOptions = LayoutOptions.End
+                Sizes.GetSize(SizeName.content_margin_small),
+                Sizes.GetSize(SizeName.size_1)),
+            HorizontalOptions = LayoutOptions.End,
+            VerticalOptions = LayoutOptions.Start,
+            Margin = new Thickness(0, 54, Sizes.GetSize(SizeName.content_margin_small), 0),
+            Stroke = Brush.Transparent,
+            StrokeShape = new RoundRectangle { CornerRadius = new CornerRadius(Sizes.GetSize(SizeName.radius_xlarge)) }
         };
-        LayoutEffect.SetCornerRadius(m_collapsedPill, new CornerRadius(Sizes.GetSize(SizeName.radius_xlarge)));
-        m_collapsedPill.Add(pillContent);
+        m_collapsedPill.Content = pillContent;
 
         var collapsedTap = new TapGestureRecognizer();
         collapsedTap.Tapped += async (_, _) => await AnimateExpand();
@@ -139,9 +133,7 @@ public LayoutDiagnosticsOverlay()
             Style = Styles.GetButtonStyle(ButtonStyle.CloseIconSmall),
             VerticalOptions = LayoutOptions.Center
         };
-        var collapseTap = new TapGestureRecognizer();
-        collapseTap.Tapped += async (_, _) => await AnimateCollapse();
-        collapseButton.GestureRecognizers.Add(collapseTap);
+        collapseButton.Clicked += async (_, _) => await AnimateCollapse();
 
         var textStack = new VerticalStackLayout { Spacing = Sizes.GetSize(SizeName.size_half) };
         textStack.Add(statusRow);
@@ -173,13 +165,16 @@ public LayoutDiagnosticsOverlay()
         m_expandedContent.Add(buttonRow);
         Grid.SetColumn(buttonRow, 1);
 
-        m_expandedPanel = new Grid
+        m_expandedPanel = new Border
         {
             BackgroundColor = Colors.GetColor(ColorName.color_surface_backdrop),
-            HorizontalOptions = LayoutOptions.End
+            HorizontalOptions = LayoutOptions.End,
+            VerticalOptions = LayoutOptions.Start,
+            Margin = new Thickness(0, 54, Sizes.GetSize(SizeName.content_margin_small), 0),
+            Stroke = Brush.Transparent,
+            StrokeShape = new RoundRectangle { CornerRadius = new CornerRadius(Sizes.GetSize(SizeName.radius_large)) }
         };
-        LayoutEffect.SetCornerRadius(m_expandedPanel, new CornerRadius(Sizes.GetSize(SizeName.radius_large)));
-        m_expandedPanel.Add(m_expandedContent);
+        m_expandedPanel.Content = m_expandedContent;
 
         this.Add(m_collapsedPill);
         this.Add(m_expandedPanel);

src/library/DIPS.Mobile.UI/API/Diagnostics/iOS/LayoutDiagnosticsService.cs

@@ -36,9 +36,13 @@ private static partial void AttachOverlay()
 
         rootVc.View!.AddSubview(uiView);
 
+        // Pin to all edges — MAUI's layout system positions content internally
+        // via HorizontalOptions.End + VerticalOptions.Start + Margin on the overlay
         NSLayoutConstraint.ActivateConstraints([
-            uiView.TopAnchor.ConstraintEqualTo(rootVc.View.SafeAreaLayoutGuide.TopAnchor, 8),
-            uiView.TrailingAnchor.ConstraintEqualTo(rootVc.View.SafeAreaLayoutGuide.TrailingAnchor, -8)
+            uiView.TopAnchor.ConstraintEqualTo(rootVc.View.TopAnchor),
+            uiView.LeadingAnchor.ConstraintEqualTo(rootVc.View.LeadingAnchor),
+            uiView.TrailingAnchor.ConstraintEqualTo(rootVc.View.TrailingAnchor),
+            uiView.BottomAnchor.ConstraintEqualTo(rootVc.View.BottomAnchor)
         ]);
     }
 
@@ -88,7 +92,9 @@ private class OverlayWindow(UIWindowScene scene) : UIWindow(scene)
         public override UIView? HitTest(CGPoint point, UIEvent? uievent)
         {
             var hit = base.HitTest(point, uievent);
-            if (hit is null || hit == this || hit == RootViewController?.View)
+            // Pass through touches on empty areas: window, VC view, or the full-screen MAUI container
+            if (hit is null || hit == this || hit == RootViewController?.View 
+                || hit.Tag == LayoutDiagnosticsOverlay.OverlayIdentifier)
                 return null;
             return hit;
         }

wiki/Layout-Diagnostics.md

@@ -0,0 +1,90 @@
+A runtime diagnostics tool for profiling .NET MAUI layout performance on iOS and Android. It captures per-element **measure** and **arrange** counts during page navigation and bottom sheet presentation, helping developers identify layout thrashing — views that are measured or arranged far more than necessary.
+
+# How It Works
+
+.NET MAUI's layout system uses a two-phase process for every frame where layout is needed ([source](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/layouts/custom#layout-process)):
+
+1. **Measure phase** — The framework calls `IView.Measure()` on each view to determine its desired size given constraints. Layouts call `Measure()` on all their children recursively, bottom-up.
+2. **Arrange phase** — The framework calls `IView.Arrange()` on each view to assign its final position and bounds within the parent layout.
+
+These phases can be triggered multiple times per frame. A parent layout may speculatively measure children, change constraints, and re-measure. Deeply nested layouts with complex constraints can cause exponential measure/arrange calls — known as **layout thrashing**.
+
+Layout Diagnostics hooks into MAUI's built-in `System.Diagnostics.Metrics` instruments (`maui.layout.measure_count`, `maui.layout.arrange_count`) via `MeterListener` to count every measure and arrange call per element type and instance.
+
+# Usage
+
+## Prerequisites
+
+Register metrics in `MauiProgram.cs` **before** `.UseMauiApp<App>()`:
+
+```csharp
+builder.Services.AddMetrics(); // Microsoft.Extensions.Diagnostics
+```
+
+## Initialize
+
+```csharp
+// Show the floating overlay (dormant — not yet recording)
+LayoutDiagnosticsService.Initialize();
+```
+
+## API
+
+| Member | Description |
+|---|---|
+| `Initialize()` | Shows the floating overlay pill |
+| `Teardown()` | Removes the overlay and tears down the system |
+| `Enable()` | Starts capturing layout metrics |
+| `Disable()` | Stops capturing, returns all snapshots |
+| `Toggle()` | Toggles between Enable/Disable |
+| `ClearSnapshots()` | Clears all completed snapshots |
+| `ExportAllToJson()` | Exports all snapshots as a JSON string |
+| `IsEnabled` | Whether diagnostics are currently capturing |
+| `IsInitialized` | Whether the overlay has been initialized |
+| `CompletedSnapshots` | All snapshots captured during this session |
+| `CurrentSnapshot` | The in-progress snapshot (null if none) |
+| `SnapshotCompleted` | Event raised when a snapshot finishes |
+
+## Automatic Snapshots
+
+Snapshots are automatically created and ended during page and bottom sheet lifecycle:
+
+- `ContentPage.OnNavigatedTo()` → `BeginSnapshot("Page: {TypeName}")`
+- `ContentPage.OnDisappearing()` → `EndSnapshot()`
+- `BottomSheet.OnAppearing()` → `BeginSnapshot("BottomSheet: {TypeName}")`
+- `BottomSheet.OnDisappearing()` → `EndSnapshot()`
+
+## Reading Snapshot Data
+
+Each `LayoutDiagnosticsSnapshot` contains:
+
+- **`SourceName`** — What triggered it (e.g., "Page: HomePage")
+- **`TotalMeasureCount` / `TotalArrangeCount`** — Aggregate counts
+- **`MeasureCountsByType` / `ArrangeCountsByType`** — Per-type breakdown (e.g., `"Microsoft.Maui.Controls.Label": 45`)
+- **`MeasureInstancesByType`** — Unique instances per type, enabling per-instance averages
+- **`Warnings`** — Types exceeding an average of 3 layout passes per instance
+
+## Interpreting Results
+
+| Metric | Healthy | Investigate |
+|---|---|---|
+| Avg measures per instance | 1–2× | > 3× (flagged with ⚠️) |
+| Total measures for a page | < 200 | > 500 |
+
+Common causes of high measure counts:
+- Deeply nested layouts (Grid inside StackLayout inside ScrollView)
+- `Auto`-sized rows/columns that cause re-measure cascades
+- Changing `IsVisible` or `Text` on elements during layout
+
+## Overlay
+
+The diagnostics overlay is a floating pill that stays visible over all content, including modals and bottom sheets:
+
+- **iOS**: Rendered in a separate `UIWindow` at `UIWindowLevel.Alert - 1`
+- **Android**: Uses `TranslationZ` for z-ordering and re-parents to dialog `DecorView` when dialogs open
+
+Tap the pill to expand and see live recording status, start/stop controls, and the current snapshot summary.
+
+# Properties
+
+Inspect the [`LayoutDiagnosticsService`](https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/API/Diagnostics/LayoutDiagnosticsService.cs) and [`LayoutDiagnosticsSnapshot`](https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/API/Diagnostics/LayoutDiagnosticsSnapshot.cs) classes for the full API surface.