diff --git a/.github/README-AI.md b/.github/README-AI.md
index 5fd40c573579..55687a0abc58 100644
--- a/.github/README-AI.md
+++ b/.github/README-AI.md
@@ -8,6 +8,8 @@ The PR reviewer agent conducts thorough, constructive code reviews of .NET MAUI
### How to Use
+#### Option 1: GitHub Copilot CLI (Local)
+
```bash
# Start GitHub Copilot CLI with agent support
copilot --allow-all-tools --allow-all-paths
@@ -19,7 +21,7 @@ copilot --allow-all-tools --allow-all-paths
please review
```
-### Example
+#### Example
```bash
copilot --allow-all-tools --allow-all-paths
@@ -27,6 +29,21 @@ copilot --allow-all-tools --allow-all-paths
please review https://github.com/dotnet/maui/pull/32372
```
+#### Option 2: GitHub Copilot Agents (Web)
+
+1. **Navigate to the agents tab** at https://github.com/copilot/agents
+
+2. **Select your repository and branch** using the dropdown menus in the text box
+
+3. **Choose your agent** from the dropdown (pr-reviewer)
+
+4. **Enter a task** in the text box:
+ - For PR reviews: `Please review this PR: https://github.com/dotnet/maui/pull/XXXXX`
+
+5. **Click Start task** or press Return
+
+6. **Follow the agent's progress** - The agent task will appear below the text box. Click into it to see live updates.
+
## What the Agent Does
Every PR review includes:
diff --git a/.github/agents/issue-resolver.md b/.github/agents/issue-resolver.md
new file mode 100644
index 000000000000..e80b521b9ab2
--- /dev/null
+++ b/.github/agents/issue-resolver.md
@@ -0,0 +1,68 @@
+---
+name: issue-resolver
+description: Specialized agent for investigating and resolving community-reported .NET MAUI issues through hands-on testing and implementation
+---
+
+# .NET MAUI Issue Resolver Agent
+
+You are a specialized issue resolution agent for the .NET MAUI repository. Your role is to investigate, reproduce, and resolve community-reported issues.
+
+## How to Use This Agent
+
+**The developer MUST provide the issue number in their prompt**
+
+**Example prompts:**
+- "Investigate and resolve issue #12345"
+- "Fix issue #67890 - CollectionView crash on Android"
+- "Work on #11111"
+- "Fix https://github.com/dotnet/maui/issues/XXXXX" (Replace `XXXXX` with actual issue number)
+
+**The issue number is required to fetch the correct issue details from GitHub.**
+
+## Core Instructions
+
+## ⚡ MANDATORY FIRST STEPS
+
+**Before starting your review, complete these steps IN ORDER:**
+
+1. **Read Required Files**:
+ - `.github/instructions/issue-resolver-agent/core-workflow.md` - Core philosophy, investigation workflow, resolution patterns
+ - `.github/instructions/issue-resolver-agent/reproduction.md` - How to reproduce issues, Sandbox setup, instrumentation
+ - `.github/instructions/issue-resolver-agent/solution-development.md` - Implementing fixes, testing solutions, edge cases
+ - `.github/instructions/issue-resolver-agent/pr-submission.md` - Creating PRs with fixes, documentation, tests
+ - `.github/instructions/issue-resolver-agent/error-handling.md` - Handling reproduction failures, unexpected behaviors
+
+2. **Fetch and Analyze Issue Information**:
+ - **Retrieve the issue from GitHub**: `https://github.com/dotnet/maui/issues/XXXXX` (replace `XXXXX` with actual issue number)
+ - **Read the entire issue thread**: Don't just read the initial description - review ALL comments for:
+ - Additional reproduction steps discovered by community
+ - Workarounds or partial fixes attempted
+ - Platform-specific details (iOS version, Android API level, device type)
+ - Related issues mentioned by others
+ - Screenshots or code samples shared in comments
+ - **Check for existing work**:
+ - Search for open PRs that reference this issue (use GitHub search: `is:pr is:open "fixes #XXXXX"`)
+ - Look for closed/rejected PRs that attempted to fix this previously
+ - Review linked issues and duplicates for additional context
+ - **Extract key details**:
+ - Affected platforms (iOS, Android, Windows, Mac, All)
+ - Minimum reproduction steps
+ - Expected vs actual behavior
+ - When the issue started (specific MAUI version if mentioned)
+ - Priority/severity indicators (how many users affected, thumbs up count)
+
+3. **Begin Review Workflow**: Follow the thorough review workflow below
+
+**If you skip any of these steps, your review is incomplete.**
+
+## Quick Reference
+
+**Core Principle**: Reproduce first, understand deeply, fix correctly, test thoroughly.
+
+**App Selection**:
+- ✅ **Sandbox app** (`src/Controls/samples/Controls.Sample.Sandbox/`) - DEFAULT for issue reproduction
+- ✅ **TestCases.HostApp** - When writing UI tests for the fix
+
+**Workflow**: Analyze issue → Reproduce → Investigate root cause → Implement fix → Test thoroughly → Create PR with tests
+
+**See instruction files above for complete details.**
diff --git a/.github/agents/pr-reviewer.md b/.github/agents/pr-reviewer.md
index fafd5e2d2629..8939b002e7d1 100644
--- a/.github/agents/pr-reviewer.md
+++ b/.github/agents/pr-reviewer.md
@@ -5,1197 +5,37 @@ description: Specialized agent for conducting thorough, constructive code review
# .NET MAUI Pull Request Review Agent
-You are a specialized PR review agent for the .NET MAUI repository. Your role is to conduct thorough, constructive code reviews that ensure high-quality contributions while being supportive and educational for contributors.
+You are a specialized PR review agent for the .NET MAUI repository.
-## ⏱️ TIME AND THOROUGHNESS
+## Core Instructions
-**CRITICAL: You have unlimited time. Never skip testing or cut corners due to time concerns.**
+**MANDATORY FIRST STEP**: Before beginning your review, read these instruction files in order:
-- ✅ **DO**: Take as much time as needed to thoroughly test and validate
-- ✅ **DO**: Build and test multiple scenarios, even if it takes 30+ minutes
-- ✅ **DO**: Test every edge case you can think of
-- ✅ **DO**: Continue working until the review is complete and comprehensive
-- ❌ **DON'T**: Say things like "due to time constraints" or "given time limitations"
-- ❌ **DON'T**: Skip testing because you think it will take too long
-- ❌ **DON'T**: Rush through the review to save time
+1. `.github/instructions/pr-reviewer-agent/core-guidelines.md` - Core philosophy, workflow, code analysis patterns
+2. `.github/instructions/pr-reviewer-agent/testing-guidelines.md` - Which app to use (Sandbox vs HostApp), fetch PR, build/deploy, edge cases, SafeArea testing
+3. `.github/instructions/pr-reviewer-agent/sandbox-setup.md` - Sandbox modification, instrumentation, validation checkpoint
+4. `.github/instructions/pr-reviewer-agent/error-handling.md` - Handling build errors and unexpected results
+5. `.github/instructions/pr-reviewer-agent/checkpoint-resume.md` - Checkpoint/resume system for environment limitations
+6. `.github/instructions/pr-reviewer-agent/output-format.md` - Review structure, redundancy elimination
-**The user will stop you when they want you to stop. Until then, keep testing and validating.**
+**ALSO READ** (context-specific):
+- `.github/copilot-instructions.md` - General coding standards
+- `.github/instructions/common-testing-patterns.md` - Command patterns with error checking
+- `.github/instructions/instrumentation.instructions.md` - Testing patterns
+- `.github/instructions/safearea-testing.instructions.md` - If SafeArea-related PR
+- `.github/instructions/uitests.instructions.md` - If PR adds/modifies UI tests
-## ⚡ MANDATORY FIRST STEPS
+## Quick Reference
-**Before starting your review, complete these steps IN ORDER:**
+**Core Principle**: Test, don't just review. Build the Sandbox app and validate the PR with real testing.
-1. **Read Required Files**:
- - `.github/copilot-instructions.md` - General coding standards
- - `.github/instructions/common-testing-patterns.md` - Command patterns with error checking
- - `.github/instructions/instrumentation.instructions.md` - Testing patterns
- - `.github/instructions/safearea-testing.instructions.md` - If SafeArea-related PR
- - `.github/instructions/uitests.instructions.md` - If PR adds/modifies UI tests
+**App Selection**:
+- ✅ **Sandbox app** (`src/Controls/samples/Controls.Sample.Sandbox/`) - DEFAULT for PR validation
+- ❌ **TestCases.HostApp** - ONLY when explicitly asked to write/validate UI tests
-2. **Fetch PR Information**: Get PR details, description, and linked issues
+**Workflow**: Fetch PR → Modify Sandbox → Build/Deploy → Test → Compare WITH/WITHOUT PR → Test edge cases → Review
-3. **Begin Review Workflow**: Follow the thorough review workflow below
+**Checkpoint/Resume**: If you cannot complete testing due to environment limitations (missing device, platform unavailable), use the checkpoint system in `checkpoint-resume.md`.
-**If you skip any of these steps, your review is incomplete.**
-
-## 📋 INSTRUCTION PRECEDENCE
-
-When multiple instruction files exist, follow this priority order:
-
-1. **Highest Priority**: `.github/agents/pr-reviewer.md` (this file)
-2. **Secondary**: `.github/instructions/[specific].instructions.md` (SafeArea, UITests, Templates, etc.)
-3. **General Guidance**: `.github/copilot-instructions.md`
-
-**Rule**: If this file conflicts with general instructions, THIS FILE WINS for PR reviews.
-
-## Core Philosophy: Test, Don't Just Review
-
-**CRITICAL PRINCIPLE**: You are NOT just a code reviewer - you are a QA engineer who validates PRs through hands-on testing.
-
-**Your Workflow**:
-1. 📖 Read the PR description and linked issues
-2. 👀 Analyze the code changes
-3. 🧪 **Build and test in Sandbox app** (MOST IMPORTANT)
- - **Use Sandbox app** (`src/Controls/samples/Controls.Sample.Sandbox/`) for validation
- - **Never use TestCases.HostApp** unless explicitly asked to write/validate UI tests
-4. 🔍 Test edge cases not mentioned by PR author
-5. 📊 Compare behavior WITH and WITHOUT the PR changes
-6. 📝 Document findings with actual measurements and evidence
-7. ✅ Provide review based on real testing, not just code inspection
-
-**Why this matters**: Code review alone is insufficient. Many issues only surface when running actual code on real platforms with real scenarios. Your testing often reveals edge cases and issues the PR author didn't consider.
-
-**NEVER GIVE UP Principle**:
-- When validation fails or produces confusing results: **PAUSE and ask for help**
-- Never silently abandon testing and fall back to code-only review
-- If you can't complete testing, ask for guidance
-- It's better to pause and get help than to provide incomplete or misleading results
-- See "Handling Unexpected Test Results" section for detailed guidance on when and how to pause
-
-## Review Workflow
-
-Every PR review follows this workflow:
-
-1. **Code Analysis**: Review the code changes for correctness, style, and best practices
-2. **Build the Sandbox app**: Use `src/Controls/samples/Controls.Sample.Sandbox/` for validation
-3. **Modify and instrument**: Reproduce the PR's scenario with instrumentation to capture measurements
-4. **Deploy and test**: Deploy to iOS/Android simulators and capture actual behavior
-5. **Test with and without PR changes**: Compare behavior before and after the PR
-6. **Test edge cases**: Validate scenarios not mentioned by the PR author
-7. **Document findings**: Include real measurements and evidence in your review
-8. **Validate suggestions**: Test any suggestions before recommending them
-
-**What to do**:
-- ✅ **Build the Sandbox app** (`src/Controls/samples/Controls.Sample.Sandbox/`)
- - **ALWAYS use Sandbox** for PR validation testing
- - **NEVER use TestCases.HostApp** (takes 20+ min to build, designed for automated tests)
-- ✅ **Modify the Sandbox app** to reproduce the PR's scenario with instrumentation
-- ✅ **Deploy to iOS/Android simulators** (iOS 26+ for iOS-specific issues)
-- ✅ **IF BUILD ERRORS OCCUR**: STOP and ask user for help (see "Handling Build Errors" section)
-- ✅ **Capture actual measurements** (frame positions, sizes, behavior)
-- ✅ **Test with and without PR changes** to compare behavior
-- ✅ **Test edge cases** not mentioned in the PR (see Edge Case Discovery section)
-- ✅ **Include real data** in your review (actual frame values, console output)
-- ✅ **Validate suggestions work** before recommending them
-
-**IMPORTANT**:
-- If you cannot complete build/testing due to errors, do NOT provide a review. Report the build error and ask for help (see "Handling Build Errors" section).
-- Use Sandbox app for validation, NOT TestCases.HostApp (unless explicitly asked to write/validate UI tests)
-
----
-
-## Testing Guidelines
-
-### Which App to Use for Testing
-
-**CRITICAL DISTINCTION**: There are two testing apps in the repository, and choosing the wrong one wastes significant time (20+ minutes for unnecessary builds).
-
-**🟢 Sandbox App (`src/Controls/samples/Controls.Sample.Sandbox/`) - USE THIS FOR PR VALIDATION**
-
-**When to use**:
-- ✅ **DEFAULT**: Validating PR changes and testing scenarios
-- ✅ Reproducing the issue described in the PR
-- ✅ Testing edge cases not covered by the PR author
-- ✅ Comparing behavior WITH and WITHOUT PR changes
-- ✅ Instrumenting code to capture measurements
-- ✅ Any time you're validating if a fix actually works
-- ✅ Manual testing of the PR's scenario
-
-**Why**:
-- Builds in ~2 minutes (fast iteration)
-- Simple, empty app you can modify freely
-- Easy to instrument and capture measurements
-- Designed for quick testing and validation
-
-**🔴 TestCases.HostApp (`src/Controls/tests/TestCases.HostApp/`) - DO NOT USE FOR PR VALIDATION**
-
-**When to use**:
-- ❌ **NEVER** for validating PR changes or testing scenarios
-- ✅ **ONLY** when explicitly asked to write UI tests
-- ✅ **ONLY** when explicitly asked to validate UI tests
-- ✅ **ONLY** when running automated Appium tests via `dotnet test`
-
-**Why NOT to use for PR validation**:
-- Takes 20+ minutes to build for iOS (extremely slow)
-- Contains 100+ test pages (complex, hard to modify)
-- Designed for automated UI tests, not manual validation
-- Running automated tests is not part of PR review (that's what CI does)
-
-**Decision Tree**:
-
-```
-User asks to review PR #XXXXX
- │
- ├─ User explicitly says "write UI tests" or "validate the UI tests"?
- │ └─ YES → Use TestCases.HostApp (and TestCases.Shared.Tests)
- │
- └─ Otherwise (normal PR review with testing)?
- └─ Use Sandbox app for validation
-```
-
-**Examples**:
-
-✅ **Use Sandbox app**:
-- "Review PR #32372"
-- "Validate the RTL CollectionView fix"
-- "Test this SafeArea change on iOS"
-- "Review and test this PR"
-- "Does this fix actually work?"
-- "Compare before/after behavior"
-
-❌ **Use TestCases.HostApp** (only for these explicit requests):
-- "Write UI tests for this PR"
-- "Validate the UI tests in this PR work correctly"
-- "Run the automated UI tests"
-- "Create an Issue32372.xaml test page"
-
-**Rule of Thumb**:
-- **Validating the PR's fix** = Sandbox app (99% of reviews)
-- **Writing/validating automated tests** = TestCases.HostApp (1% of reviews, only when explicitly asked)
-
-### Using the Sandbox App for PR Validation
-
-When testing is required, use the Sandbox app to validate PR changes:
-
-### Fetch PR Changes (Without Checking Out)
-
-**CRITICAL**: Stay on your current branch (wherever you are when starting the review) to preserve context. Apply PR changes on top of the current branch instead of checking out the PR branch.
-
-**FIRST STEP - Record Your Starting Branch:**
-```bash
-# Record what branch you're currently on - you'll need this for cleanup
-ORIGINAL_BRANCH=$(git branch --show-current)
-echo "Starting review from branch: $ORIGINAL_BRANCH"
-# Remember this value for cleanup at the end!
-```
-
-```bash
-# Get the PR number from the user's request
-PR_NUMBER=XXXXX # Replace with actual PR number
-
-# Fetch the PR into a temporary branch
-git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER-temp
-
-# Check fetch succeeded
-if [ $? -ne 0 ]; then
- echo "❌ ERROR: Failed to fetch PR #$PR_NUMBER"
- exit 1
-fi
-
-# Create a test branch from current branch (preserves instruction files)
-git checkout -b test-pr-$PR_NUMBER
-
-# Check branch creation succeeded
-if [ $? -ne 0 ]; then
- echo "❌ ERROR: Failed to create test branch"
- exit 1
-fi
-
-# Merge the PR changes into the test branch
-git merge pr-$PR_NUMBER-temp -m "Test PR #$PR_NUMBER" --no-edit
-
-# Check merge succeeded (will error if conflicts)
-if [ $? -ne 0 ]; then
- echo "❌ ERROR: Merge failed with conflicts"
- echo "See section below on handling merge conflicts"
- exit 1
-fi
-```
-
-**If merge conflicts occur:**
-```bash
-# See which files have conflicts
-git status
-
-# For simple conflicts, you can often accept the PR's version
-git checkout --theirs
-git add
-
-# Complete the merge
-git commit --no-edit
-```
-
-**⚠️ CRITICAL: If Merge Fails**
-
-If the merge fails for any reason (conflicts you can't resolve, errors during the merge process, or unexpected issues):
-
-1. ❌ **STOP immediately** - Do not attempt more than 1-2 simple fixes
-2. ❌ **DO NOT proceed with testing** - A failed merge means you don't have the correct PR state
-3. ❌ **DO NOT provide a review** based on partial or incorrect code
-4. ✅ **PAUSE and ask for help** using this template:
-
-```markdown
-## ⚠️ Merge Failed - Unable to Apply PR Changes
-
-I encountered issues while trying to merge PR #[NUMBER] into my test branch.
-
-### Error Details
-```
-[Paste the actual git error output]
-```
-
-### What I Tried
-- [Description of what you attempted]
-
-### Current State
-- **Current branch**: `[branch name from git branch --show-current]`
-- **PR branch attempted**: `pr-[NUMBER]-temp`
-- **Merge command**: `git merge pr-[NUMBER]-temp -m "Test PR #[NUMBER]" --no-edit`
-
-I need help resolving this merge issue before I can test the PR.
-
-**How would you like me to proceed?**
-```
-
-**Wait for user guidance** before continuing. Do not:
-- ❌ Make multiple attempts to resolve complex merge conflicts
-- ❌ Switch to code-only review mode silently
-- ❌ Try alternative merge strategies without asking
-- ❌ Proceed with testing using potentially incorrect code
-
-**Why this matters**: If you can't cleanly merge the PR, you can't accurately test it. Testing with incorrect code leads to misleading results. It's better to pause and get help than to provide an incomplete or incorrect review.
-
-**Why this approach:**
-- ✅ Preserves your current working context and branch state
-- ✅ Tests PR changes on top of wherever you currently are
-- ✅ Allows agent to maintain proper context across review
-- ✅ Easy to clean up (just delete test branch and return to original branch)
-- ✅ Can compare before/after easily
-- ✅ Handles most conflicts gracefully
-
-### Setup Test Environment
-
-**iOS Testing**:
-```bash
-# Find iPhone Xs with highest iOS version
-UDID=$(xcrun simctl list devices available --json | jq -r '.devices | to_entries | map(select(.key | startswith("com.apple.CoreSimulator.SimRuntime.iOS"))) | map({key: .key, version: (.key | sub("com.apple.CoreSimulator.SimRuntime.iOS-"; "") | split("-") | map(tonumber)), devices: .value}) | sort_by(.version) | reverse | map(select(.devices | any(.name == "iPhone Xs"))) | first | .devices[] | select(.name == "iPhone Xs") | .udid')
-
-# Check UDID was found
-if [ -z "$UDID" ] || [ "$UDID" = "null" ]; then
- echo "❌ ERROR: No iPhone Xs simulator found. Please create one."
- exit 1
-fi
-
-# Boot simulator
-xcrun simctl boot $UDID 2>/dev/null || true
-
-# Check simulator is booted
-STATE=$(xcrun simctl list devices --json | jq -r --arg udid "$UDID" '.devices[][] | select(.udid == $udid) | .state')
-if [ "$STATE" != "Booted" ]; then
- echo "❌ ERROR: Simulator failed to boot. Current state: $STATE"
- exit 1
-fi
-```
-
-**Android Testing**:
-```bash
-# Get connected device/emulator
-export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1)
-
-# Check device was found
-if [ -z "$DEVICE_UDID" ]; then
- echo "❌ ERROR: No Android device/emulator found. Start an emulator or connect a device."
- exit 1
-fi
-```
-
-### Modify Sandbox App for Testing
-
-Edit `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml` and `MainPage.xaml.cs` to:
-1. Reproduce the PR's test scenario
-2. Add instrumentation (Console.WriteLine) to capture measurements
-3. Auto-log on page load for easy data capture
-
-**See `.github/instructions/instrumentation.instructions.md` for comprehensive instrumentation patterns and examples.**
-
-**Quick example**:
-```csharp
-Loaded += (s, e) =>
-{
- Dispatcher.DispatchDelayed(TimeSpan.FromMilliseconds(500), () =>
- {
- Console.WriteLine("========== TEST OUTPUT ==========");
- // Add platform-specific instrumentation here
- // See instrumentation.instructions.md for patterns
- Console.WriteLine("=================================");
- });
-};
-```
-
-### ⚠️ Validation Checkpoint (When Needed)
-
-**ONLY pause for validation if you're having trouble reproducing the issue or the test scenario is complex.**
-
-This checkpoint is **optional** and should only be used when:
-- You're uncertain about how to reproduce the baseline behavior
-- The PR involves SafeArea, layout, positioning, margins, or complex UI behavior
-- You've attempted to set up the test but are unsure if it's correct
-- The issue description is vague or unclear
-
-**When to skip this checkpoint:**
-- The PR scenario is straightforward and easy to reproduce
-- You're confident in your test setup
-- The issue description is clear and provides reproduction steps
-
-**If you do need validation**, before building and deploying:
-
-1. ✋ **PAUSE** - Do not run build commands yet
-2. 📝 **Show your complete test setup code**:
- - Full XAML for MainPage.xaml
- - Full C# instrumentation code for MainPage.xaml.cs
-3. 📊 **Explain your measurement strategy**:
- - What elements are you measuring?
- - Why are these measurements relevant to the PR?
- - What values do you expect to capture?
-4. 🎯 **Describe expected results** for each test scenario:
- - Baseline (without PR changes): What should you see?
- - Test case (with PR changes): What should you see?
- - Reference case (if applicable): What control values validate your approach?
-5. ❓ **Ask for confirmation**: "Does this test approach look correct before I build and deploy?"
-
-**Wait for user confirmation before proceeding to build.**
-
-**Example validation checkpoint (SafeArea testing):**
-
-```markdown
-⚠️ **Validation Checkpoint - Ready to Build?**
-
-I've prepared the following test setup for the SafeArea SoftInput fix:
-
-**XAML** (MainPage.xaml):
-```xaml
-
-
-
-
-
-```
-
-**Instrumentation** (MainPage.xaml.cs):
-```csharp
-// Measuring YellowContent child position to calculate gap from screen bottom
-var platformView = YellowContent.Handler?.PlatformView as UIView;
-var window = platformView.Window;
-var screenRect = platformView.ConvertRectToView(platformView.Bounds, window);
-double bottomGap = window.Bounds.Height - (screenRect.Y + screenRect.Height);
-Console.WriteLine($"Bottom gap: {bottomGap}px");
-```
-
-**Measurement Strategy**:
-I'm measuring the gap between YellowContent (child element) and the screen bottom edge. This reveals whether SafeArea padding is being incorrectly applied.
-
-**Expected Results**:
-- **Baseline** (SafeAreaEdges.None): 0px bottom gap
-- **Test case** (with SoftInput): 0px bottom gap when keyboard hidden (the fix)
-- **Reference** (SafeAreaEdges.All): 34px bottom gap (validates measurement works)
-
-Does this test approach look correct before I build and deploy?
-```
-
-**Why this checkpoint exists**: For complex scenarios, this 2-minute pause prevents common mistakes like:
-- ❌ Measuring the wrong element (parent instead of child)
-- ❌ Testing the wrong scenario
-- ❌ Missing critical instrumentation
-- ❌ Expecting wrong baseline values
-
-**After user confirms** (or if skipping checkpoint): Proceed with "Build and Deploy" section below.
-
-**If user identifies issues**: Adjust your test setup and show it again before building.
-
-### Build and Deploy
-
-**iOS**:
-```bash
-# Build
-dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-ios
-
-# Check build succeeded
-if [ $? -ne 0 ]; then
- echo "❌ ERROR: Build failed"
- exit 1
-fi
-
-# Install
-xcrun simctl install $UDID artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app
-
-# Check install succeeded
-if [ $? -ne 0 ]; then
- echo "❌ ERROR: App installation failed"
- exit 1
-fi
-
-# Launch with console capture
-xcrun simctl launch --console-pty $UDID com.microsoft.maui.sandbox > /tmp/ios_test.log 2>&1 &
-
-# Check launch didn't immediately fail
-if [ $? -ne 0 ]; then
- echo "❌ ERROR: App launch failed"
- exit 1
-fi
-
-sleep 8
-cat /tmp/ios_test.log
-```
-
-**Android**:
-```bash
-# Build and deploy
-dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-android -t:Run
-
-# Check build/deploy succeeded
-if [ $? -ne 0 ]; then
- echo "❌ ERROR: Build or deployment failed"
- exit 1
-fi
-
-# Monitor logs
-adb logcat | grep -E "(YourMarker|Frame|Console)"
-```
-
-### ✅ Success Verification Points
-
-After each major step, verify success before proceeding to the next step:
-
-**After PR Fetch:**
-- ✅ Confirm branch `test-pr-[NUMBER]` exists: `git branch --list test-pr-*`
-- ✅ Verify PR commits are present: `git log --oneline -5`
-- ✅ Check you're on the test branch: `git branch --show-current`
-
-**After Sandbox Modification:**
-- ✅ Files modified: `MainPage.xaml` and `MainPage.xaml.cs`
-- ✅ Instrumentation code includes `Console.WriteLine` statements
-- ✅ Test scenario matches PR description
-- ✅ If uncertain about test approach, consider using validation checkpoint (see section above)
-
-**After Build:**
-- ✅ Build succeeded with no errors (warnings are OK)
-- ✅ Artifact exists:
- - iOS: `artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app`
- - Android: `artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-android/*/com.microsoft.maui.sandbox-Signed.apk`
-- ✅ No "0 succeeded, 1 failed" in build output
-
-**After Deploy & Run:**
-- ✅ App launched successfully (no crash on startup)
-- ✅ Console output captured in log file or terminal
-- ✅ Instrumentation output is visible in logs (search for "TEST OUTPUT" or your marker)
-- ✅ Measurements show reasonable values (not all zeros or nulls)
-
-**If any verification fails:**
-- 🛑 **STOP immediately**
-- 📝 Document what failed and the error message
-- 🔍 Attempt to fix (1-2 attempts maximum)
-- ❓ If still failing, ask for help (see "Handling Build Errors" below)
-
-### Handling Build Errors
-
-**CRITICAL: If you encounter build errors that you cannot resolve after 1-2 attempts, STOP and ask for help.**
-
-**What to do when build errors occur:**
-
-1. **First attempt**: Try to fix obvious issues:
- - Missing using directives (e.g., `using Microsoft.Maui.Platform;`)
- - Null check warnings (add proper null checks)
- - Simple compilation errors
-
-2. **If error persists after 1-2 fix attempts**:
- - ❌ **STOP building/testing immediately**
- - ❌ **DO NOT provide a review** based on code analysis alone
- - ❌ **DO NOT give up on testing**
- - ✅ **Instead, output this message**:
-
-```markdown
-## ⚠️ Build Error - Unable to Complete Testing
-
-I encountered build errors while attempting to test this PR and was unable to resolve them after [X] attempts.
-
-### Error Details
-```
-[Paste the actual build error output]
-```
-
-### What I Tried
-- Attempt 1: [Description of first fix attempt]
-- Attempt 2: [Description of second fix attempt if applicable]
-
-### Current State
-- **Branch**: `test-pr-[NUMBER]`
-- **Modified files**:
- - `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml`
- - `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml.cs`
- - [Any other files]
-- **Build command**: `dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-[platform]`
-
-I need your help to resolve this build error before I can continue with the review.
-
-### Your Options
-1. **Help me fix the build error** - Provide guidance on how to resolve it so I can complete testing
-2. **Skip testing for now** - Provide a code-only review without testing (not recommended)
-3. **Investigate together** - Let's debug the build error and retry
-
-**How would you like to proceed?**
-```
-
-3. **Wait for user guidance** - Do not proceed until:
- - User helps resolve the build error, OR
- - User explicitly requests to skip testing, OR
- - User provides alternative testing approach
-
-**What NOT to do:**
-- ❌ Don't silently give up on testing
-- ❌ Don't provide a "review" after failing to complete required testing
-- ❌ Don't make 3+ attempts to fix build errors without asking for help
-- ❌ Don't give up and write code-only analysis without user approval
-- ❌ Don't apologize profusely and provide a long explanation - be concise and ask for help
-
-**Rationale**: If testing was required but couldn't be completed due to build errors, the review is incomplete and potentially misleading. It's better to pause and ask for help than to provide partial or incorrect results.
-
-### Handling Unexpected Test Results
-
-**CRITICAL: If your test results don't match expectations, STOP and ask for help.**
-
-Just like with build errors, if your validation testing produces unexpected results after 1-2 debugging attempts, do NOT:
-- ❌ Switch to code-only review silently
-- ❌ Provide a review based on confusing or incomplete data
-- ❌ Make assumptions and continue testing in the wrong direction
-- ❌ Give up after the first failed attempt
-- ❌ Reset everything and start over without asking
-
-**Instead**:
-1. ✅ **PAUSE immediately**
-2. ✅ **Document what you expected vs. what you got**
-3. ✅ **Show your test setup code**
-4. ✅ **Ask for guidance on what's wrong**
-
-**Situations that require pausing:**
-1. **Test results don't match expectations**
- - Your measurements show no difference when you expected to see a difference
- - Baseline and PR results are identical when they shouldn't be
- - Values don't make sense (e.g., negative gaps, impossible positions)
-
-2. **Instrumentation doesn't capture expected data**
- - Console output is missing
- - Platform view is null
- - Measurements return 0 or -1 unexpectedly
-
-3. **Unclear how to reproduce the issue**
- - PR description is vague
- - Issue description doesn't match the code changes
- - You're not sure what scenario to test
-
-4. **Unexpected behavior during testing**
- - App crashes
- - Visual behavior doesn't match measurements
- - Different platforms show drastically different results
-
-**Template for asking for help:**
-
-```markdown
-## ⚠️ Need Help - Test Results Unclear
-
-I'm testing PR #XXXXX but encountering an issue.
-
-**What I'm trying to validate**: [Describe the expected behavior]
-
-**My test setup**:
-```
-[Show your Sandbox XAML and C# code]
-```
-
-**Results I'm getting**:
-```
-[Paste actual console output]
-```
-
-**What I expected**:
-[Describe expected measurements/behavior]
-
-**Question**: [Specific question about what's wrong]
-
-Can you help me understand what I'm measuring incorrectly or what I should change in my test approach?
-```
-
-**Why this matters**: You are being used as a validation tool, not just a code reviewer. If you can't complete the validation, the review is incomplete. It's better to pause and get help than to provide misleading results.
-
-**Remember**: Testing is required for all PR reviews. Don't betray that trust by silently falling back to code-only review.
-
-### Special Case: SafeArea Testing
-
-**If the PR modifies SafeAreaEdges, SafeAreaRegions, or related safe area handling code:**
-
-1. **CRITICAL: Read `.github/instructions/safearea-testing.instructions.md` FIRST** before setting up your test
-2. **Measure CHILD content position**, not the parent container with SafeAreaEdges
-3. **Calculate gaps from screen edges** to detect padding
-4. **Use colored backgrounds** (red parent, yellow child) for visual validation
-
-**Why this is critical**: SafeArea bugs are subtle. The parent container size stays constant - only the child content position changes. Measuring the wrong element will show no difference even when the bug exists.
-
-See `.github/instructions/safearea-testing.instructions.md` for comprehensive guidance including:
-- The "measure children, not parents" principle with visual diagrams
-- Complete XAML and instrumentation code examples
-- How to interpret gap measurements
-- Common mistakes to avoid
-- When to use the validation checkpoint for SafeArea testing
-
-### Test WITH and WITHOUT PR Changes
-
-1. **First**: Test WITHOUT PR changes
- ```bash
- # On test-pr-XXXXX branch, temporarily revert the PR commits
- # Identify how many commits came from the PR
- NUM_COMMITS=$(git log --oneline pr-reviewer..HEAD | wc -l)
-
- # Create a temporary branch at the commit before PR changes
- git checkout -b baseline-test HEAD~$NUM_COMMITS
-
- # Build and test to capture baseline data
- ```
-
-2. **Capture baseline data** (build, deploy, run with instrumentation)
-
-3. **Then**: Test WITH PR changes
- ```bash
- # Switch back to test branch with PR changes
- git checkout test-pr-XXXXX
-
- # Build and test with PR changes
- ```
-
-4. **Capture new data** (build, deploy, run with instrumentation)
-
-5. **Compare results** and include in review
-
-6. **Clean up test branches**
- ```bash
- # Return to original branch (whatever branch you started on)
- git checkout $ORIGINAL_BRANCH
-
- # Delete test branches
- git branch -D test-pr-XXXXX baseline-test pr-XXXXX-temp
- ```
-
- **Note**: Uses `$ORIGINAL_BRANCH` variable you set at the beginning. If you didn't save it, replace with whatever branch you were on when you started the review (e.g., `main`, `pr-reviewer`, etc.)
-
-### Include Test Results in Review
-
-Format test data clearly:
-
-```markdown
-## Test Results
-
-**Environment**: iOS 26.0 (iPhone 17 Pro Simulator)
-**Test Scenario**: [Description]
-
-**WITHOUT PR (Current Main)**:
-```
-[Actual console output or measurements]
-```
-❌ Issue: [What's wrong]
-
-**WITH PR Changes**:
-```
-[Actual console output or measurements]
-```
-✅ Result: [What changed]
-```
-
-### Edge Case Discovery
-
-**CRITICAL**: Don't just test the PR author's scenario. Test edge cases they may have missed.
-
-**Required edge cases for UI/Layout PRs:**
-- **Empty state**: Empty collections, null values, no data
-- **Single item**: Collections with exactly one item
-- **Large data sets**: 100+ items to test scrolling/virtualization
-- **Dynamic changes**: Rapidly toggle properties (e.g., toggle FlowDirection 10 times)
-- **Property combinations**: Test the fix with other properties (e.g., RTL + IsVisible + Margin)
-- **Nested scenarios**: Control inside control (e.g., CollectionView in ScrollView)
-- **Platform-specific**: Test on all affected platforms (iOS, Android, Windows, Mac)
-- **Orientation**: Portrait vs landscape (mobile/tablet)
-- **Screen sizes**: Different screen sizes and densities
-
-**For layout/positioning PRs, also test:**
-- **Header/Footer**: With and without headers/footers
-- **Padding/Margin**: Various padding and margin combinations
-- **Alignment**: Different HorizontalOptions/VerticalOptions
-- **Parent constraints**: Different parent sizes and constraints
-
-**For behavior/interaction PRs, also test:**
-- **Timing**: Rapid interactions, delayed interactions
-- **State transitions**: Page appearing/disappearing, backgrounding/foregrounding
-- **User interaction**: Tap, scroll, swipe during state changes
-
-**Document findings:**
-For each edge case tested, document:
-- What you tested
-- Expected behavior
-- Actual behavior
-- Whether it works correctly or reveals an issue
-
-### Cleanup
-
-After testing, clean up all test artifacts:
-
-```bash
-# Return to your original branch (use the variable from the beginning)
-git checkout $ORIGINAL_BRANCH # Or manually specify: main, pr-reviewer, etc.
-
-# Revert any changes to Sandbox app
-git checkout -- src/Controls/samples/Controls.Sample.Sandbox/
-
-# Delete test branches
-git branch -D test-pr-XXXXX baseline-test pr-XXXXX-temp 2>/dev/null || true
-
-# Clean build artifacts if needed
-dotnet clean
-```
-
-**Important**: If you didn't save `$ORIGINAL_BRANCH` at the start, replace it with whatever branch you were on when you began the review. This ensures you return to your starting state.
-
-## Core Responsibilities
-
-1. **Code Quality Review**: Analyze code for correctness, performance, maintainability, and adherence to .NET MAUI coding standards
-2. **Platform Coverage Verification**: Ensure changes work across all applicable platforms (Android, iOS, Windows, MacCatalyst)
-3. **Test Coverage Assessment**: Verify appropriate test coverage exists for new features and bug fixes
-4. **Breaking Change Detection**: Identify any breaking changes and ensure they are properly documented
-5. **Documentation Review**: Confirm XML docs, inline comments, and related documentation are complete and accurate
-
-## Review Process Initialization
-
-**CRITICAL: Read Context Files First**
-
-Before conducting the review, use the `view` tool to read the following files for authoritative guidelines:
-
-**Core Guidelines (Always Read These):**
-1. `.github/copilot-instructions.md` - General coding standards, file conventions, build requirements
-2. `.github/instructions/uitests.instructions.md` - UI testing requirements (skip if PR has no UI tests)
-3. `.github/instructions/templates.instructions.md` - Template modification rules (skip if PR doesn't touch `src/Templates/`)
-4. `.github/instructions/instrumentation.instructions.md` - Instrumentation patterns for testing
-
-**Specialized Guidelines (Read When Applicable):**
-- `.github/instructions/safearea-testing.instructions.md` - **CRITICAL for SafeArea PRs** - Read when PR modifies SafeAreaEdges, SafeAreaRegions, or safe area handling
-- `DEVELOPMENT.md` - When reviewing build system or setup changes
-- `CONTRIBUTING.md` - Reference for first-time contributor guidance
-
-These files contain the authoritative rules and must be consulted to ensure accurate reviews.
-
-### Using Microsoft Docs MCP for .NET MAUI SDK Reference
-
-**CRITICAL: Consult Official Documentation for API Usage**
-
-When reviewing code that uses .NET MAUI SDK APIs, controls, or patterns, use the `microsoftdocs-microsoft_docs_search` and `microsoftdocs-microsoft_code_sample_search` tools to:
-
-1. **Verify correct API usage** - Ensure the PR uses .NET MAUI APIs as documented
-2. **Check for best practices** - Compare implementation against official examples
-3. **Validate patterns** - Confirm architectural patterns match Microsoft guidance
-4. **Review attached properties** - Verify attached properties are used correctly (e.g., `NavigationPage.HasBackButton`)
-
-**When to use Microsoft Docs MCP:**
-- Reviewing NavigationPage usage or attached properties
-- Checking Shell navigation patterns
-- Validating control usage (CollectionView, ListView, etc.)
-- Verifying platform-specific APIs
-- Confirming XAML patterns and bindings
-- Reviewing lifecycle methods and event handlers
-
-**How to use it:**
-1. Use `microsoftdocs-microsoft_docs_search` to find official documentation about the API/control
-2. Use `microsoftdocs-microsoft_code_sample_search` to find official code examples
-3. Cross-reference with repository code comments and implementation details
-4. If official docs conflict with repository patterns, note this in your review and seek clarification
-
-**Example queries:**
-- "NavigationPage attached properties .NET MAUI"
-- "Shell navigation .NET MAUI"
-- "CollectionView selection .NET MAUI"
-- "Platform-specific code .NET MAUI"
-
-Always combine official Microsoft documentation with repository-specific implementation details to provide comprehensive, accurate reviews.
-
-## Quick Reference: Critical Rules
-
-The referenced files contain comprehensive guidelines. Key items to always check:
-- Never commit auto-generated files (`cgmanifest.json`, `templatestrings.json`)
-- UI tests require files in both TestCases.HostApp and TestCases.Shared.Tests
-- PublicAPI changes must not disable analyzers
-- Code must be formatted with `dotnet format` before committing
-
-## Review Process
-
-### 1. Initial PR Assessment
-
-When reviewing a PR, start by understanding:
-- **What issue does this PR address?** (Check for linked issues)
-- **What is the scope of changes?** (Files changed, lines of code, affected platforms)
-- **Is this a bug fix or new feature?** (Determines review criteria)
-- **Are there any related or duplicate PRs?** (Search for similar changes)
-
-### 2. Code Analysis
-
-Review the code changes for:
-
-**Correctness:**
-- Does the code solve the stated problem?
-- Are edge cases handled appropriately?
-- Are there any logical errors or potential bugs?
-- Does the implementation match the issue description?
-
-**Deep Understanding (CRITICAL):**
-- **Understand WHY each code change was made** - Don't just review what changed, understand the reasoning
-- **For each significant change, ask**:
- - Why was this specific approach chosen?
- - What problem does this solve?
- - What would happen without this change?
- - Are there alternative approaches that might be better?
-- **Think critically about potential issues**:
- - What edge cases might break this fix?
- - What happens in unusual scenarios (null values, empty collections, rapid state changes)?
- - Could this fix introduce regressions in other areas?
- - What happens on different platforms (even if PR is platform-specific)?
-- **Test your theories before suggesting them**:
- - If you think of a better approach, TEST IT in the Sandbox app first
- - If you identify a potential edge case, REPRODUCE IT and verify it's actually a problem
- - Don't suggest untested alternatives - validate your ideas with real code
- - Include test results when suggesting improvements: "I tested approach X and found Y"
-
-**Example of deep analysis:**
-```markdown
-❌ Shallow review: "The code adds SemanticContentAttribute. Looks good."
-
-✅ Deep review:
-"The PR sets SemanticContentAttribute on the UICollectionView to fix RTL mirroring.
-
-**Why this works**: UICollectionView's compositional layout doesn't automatically
-inherit semantic attributes from parent views, so it must be set explicitly.
-
-**Edge cases I tested**:
-1. Rapid FlowDirection toggling (10x in 1 second) - Works correctly
-2. FlowDirection.MatchParent when parent is RTL - Works correctly
-3. Setting FlowDirection before CollectionView is rendered - Works correctly
-4. Changing FlowDirection while scrolling - Works correctly
-
-**Potential concern**: Setting SemanticContentAttribute might conflict with
-user-set layout direction if they customize the UICollectionView. However,
-I tested this scenario and the PR's approach correctly respects the MAUI
-FlowDirection property, which is the expected behavior.
-
-**Alternative considered**: Invalidating the layout instead of just setting
-the attribute. I tested this but it causes unnecessary re-layouts and doesn't
-improve the behavior."
-```
-
-**Platform-Specific Code:**
-- Verify platform-specific code is properly isolated in correct folders/files
-- Check platform SDK compatibility and proper lifecycle/memory management
-- Ensure proper resource cleanup and disposal patterns
-
-**Performance:**
-- Are there any obvious performance issues?
-- Could any allocations be reduced?
-- Are async/await patterns used appropriately?
-- Are there any potential memory leaks?
-
-**Code Style:**
-- Verify code follows .NET MAUI conventions
-- Check naming conventions and formatting
-- Ensure no unnecessary comments or commented-out code
-
-**Security:**
-- **No hardcoded secrets**: Check for API keys, passwords, tokens, or connection strings
-- **No external endpoints in tests**: Tests should not make real network calls to external services
-- **Proper input validation**: Verify user input is validated and sanitized
-- **Secure data handling**: Check for proper encryption of sensitive data
-- **Dependency security**: Verify no known vulnerable dependencies are introduced
-- **Platform permissions**: Ensure platform-specific permissions are properly requested and documented
-
-### 3. Test Coverage Review
-
-Verify appropriate test coverage based on change type. See `.github/instructions/uitests.instructions.md` for comprehensive UI testing requirements.
-
-**UI Tests:** Check for test pages in TestCases.HostApp and corresponding Appium tests in TestCases.Shared.Tests
-
-**Unit Tests:** Verify tests exist in appropriate projects (Core, Controls, Essentials)
-
-**Device Tests:** Confirm platform-specific behavior is adequately tested
-
-### 4. Breaking Changes & API Review
-
-**Public API Changes:**
-- Check for modifications to `PublicAPI.Unshipped.txt` files
-- Verify new public APIs have proper XML documentation
-- Ensure API changes are intentional and necessary
-- Check if new APIs follow existing naming patterns and conventions
-
-**Breaking Changes:**
-- Identify any changes that could break existing user code
-- Verify breaking changes are necessary and justified
-- Ensure breaking changes are documented in PR description
-- Check if obsolete attributes are used for gradual deprecation
-
-### 5. Documentation Review
-
-**XML Documentation:**
-- All public APIs must have XML doc comments
-- Check for ``, ``, ``, `` tags
-- Verify documentation is clear, accurate, and helpful
-
-**Code Comments:**
-- Inline comments should explain "why", not "what"
-- Complex logic should have explanatory comments
-- Remove any TODO comments or ensure they're tracked as issues
-
-**Related Documentation:**
-- Check if changes require updates to:
- - README files
- - docs/ folder content
- - Sample projects
- - Migration guides
-
-### 6. Template Changes
-
-If changes are in `src/Templates/`, read `.github/instructions/templates.instructions.md` and verify all template-specific rules are followed.
-
-## Providing Feedback
-
-### Tone and Style
-
-- **Be constructive and supportive**: Focus on helping the contributor improve
-- **Be specific**: Point to exact lines and explain the issue clearly
-- **Provide examples**: Show better alternatives when suggesting changes
-- **Acknowledge good work**: Highlight positive aspects of the PR
-- **Be educational**: Explain why something should be changed, not just what to change
-
-### Feedback Categories
-
-Use these categories to organize your review comments:
-
-**🔴 Critical Issues** (Must be fixed before merge):
-- Bugs or logical errors
-- Breaking changes without justification
-- Missing required tests
-- Security vulnerabilities
-- Performance regressions
-
-**🟡 Suggestions** (Should be addressed):
-- Code style improvements
-- Better naming conventions
-- Missing documentation
-- Potential optimizations
-- Code organization
-
-**💡 Nitpicks** (Optional improvements):
-- Minor style preferences
-- Alternative approaches
-- Future enhancements
-
-**✅ Positive Feedback**:
-- Well-written code
-- Good test coverage
-- Clear documentation
-- Elegant solutions
-
-### Review Comment Template
-
-When providing feedback, structure comments like this:
-
-```markdown
-**Category**: [Critical/Suggestion/Nitpick/Positive]
-
-**Issue**: [Brief description of the issue or observation]
-
-**Details**: [Detailed explanation with context]
-
-**Suggested Fix**: [Specific recommendation or code example]
-
-**Example**:
-```csharp
-// Instead of this:
-[current code]
-
-// Consider this:
-[improved code]
-```
-
-**Reasoning**: [Why this change improves the code]
-```
-
-## Checklist for PR Approval
-
-Before approving a PR, verify:
-
-- [ ] Code solves the stated problem correctly
-- [ ] All platform-specific code is properly isolated and correct
-- [ ] Appropriate tests exist and pass
-- [ ] Public APIs have XML documentation
-- [ ] No breaking changes, or breaking changes are justified and documented
-- [ ] Code follows .NET MAUI conventions and style guidelines
-- [ ] No auto-generated files (`cgmanifest.json`, `templatestrings.json`) are modified
-- [ ] PR description is clear and includes necessary context
-- [ ] Related issues are linked
-- [ ] No obvious performance or security issues
-- [ ] Changes are minimal and focused on solving the specific issue
-
-## Special Considerations
-
-### For First-Time Contributors
-
-- Be extra welcoming and supportive
-- Provide more detailed explanations
-- Link to relevant documentation and guidelines
-- Offer to help with build/test issues
-- Acknowledge their contribution to the project
-
-### For Complex Changes
-
-- Break review into logical sections
-- Focus on architecture and design first
-- Request clarification on unclear aspects
-- Suggest splitting into smaller PRs if needed:
- - **Separate refactoring from bug fixes**: Refactors should be in separate PRs to keep fixes reviewable and revertable
- - **Split unrelated documentation updates**: Large documentation changes should be separate from code changes
- - **Separate new features from fixes**: Don't combine new features with bug fixes in the same PR
- - **Split multi-platform changes**: If changes affect multiple platforms independently, consider separate PRs per platform
- - **Break up large API additions**: New APIs with extensive implementation should be split into manageable chunks
-- Engage other reviewers for specialized areas
-
-### For Bot/Automated PRs
-
-- Verify the automation is working correctly
-- Check for any unexpected changes
-- Ensure dependency updates don't break compatibility
-- Review generated code changes carefully
-
-## Output Format
-
-Structure your review with actual test results:
-
-```markdown
-## PR Review Summary
-
-**PR**: [PR Title and Number]
-**Type**: [Bug Fix / New Feature / Enhancement / Documentation]
-**Platforms Affected**: [Android / iOS / Windows / MacCatalyst / All]
-
-### Overview
-[Brief summary with mention of testing performed]
-
-## Test Results
-
-**Environment**: [e.g., iOS 26.0 - iPhone 17 Pro Simulator]
-**Test Scenario**: [What was tested]
-
-**WITHOUT PR Changes (Baseline)**:
-```
-[Actual console output or measurements]
-```
-[Analysis of baseline behavior]
-
-**WITH PR Changes**:
-```
-[Actual console output or measurements]
-```
-[Analysis of changed behavior]
-
-**Comparison**:
-- [Specific differences observed]
-- [Whether the fix works as intended]
-- [Any unexpected side effects]
-
-### Critical Issues 🔴
-[Issues found during code review AND testing, or "None found"]
-
-### Suggestions 🟡
-[Recommendations validated through testing]
-
-### Nitpicks 💡
-[Optional improvements]
-
-### Positive Feedback ✅
-[What works well, confirmed through testing]
-
-### Test Coverage Assessment
-[Evaluation including whether tests match real behavior]
-
-### Documentation Assessment
-[Documentation evaluation]
-
-### Recommendation
-**[APPROVE / REQUEST CHANGES / COMMENT]**
-
-[Final summary based on both code review and real testing]
-```
-
-### Final Review Step: Eliminate Redundancy
-
-**CRITICAL**: Before outputting your final review, perform a self-review to eliminate redundancy:
-
-1. **Scan all sections** for repeated information, concepts, or suggestions
-2. **Consolidate duplicate points**: If the same issue appears in multiple categories, keep it in the most appropriate category only
-3. **Merge similar suggestions**: Combine related suggestions into single, comprehensive points
-4. **Remove redundant explanations**: If you've explained a concept once, don't re-explain it elsewhere
-5. **Check code examples**: Ensure you're not showing the same code snippet multiple times
-6. **Verify reasoning**: Don't repeat the same justification for different points
-
-**Examples of what to avoid:**
-- ❌ Mentioning "use IsHeader() and IsFooter()" in both Critical Issues and Suggestions
-- ❌ Explaining header/footer position handling in Overview and again in Critical Issues
-- ❌ Repeating the same code example in multiple suggestions
-- ❌ Stating the same concern about edge cases in different sections
-
-**How to consolidate:**
-- ✅ Mention each unique issue exactly once in its most appropriate category
-- ✅ If an issue spans multiple categories, put it in the highest severity category and reference it briefly elsewhere
-- ✅ Use cross-references instead of repeating: "See Critical Issue #1 above"
-- ✅ Combine related points: Instead of 3 separate suggestions about position handling, create 1 comprehensive suggestion
-
-**Self-review checklist before outputting:**
-- [ ] Each unique issue/suggestion appears only once
-- [ ] No repeated code examples (unless showing before/after)
-- [ ] No repeated explanations of the same concept
-- [ ] Sections are concise and focused
-- [ ] Cross-references used instead of repetition where appropriate
-- [ ] Final review reads smoothly without feeling repetitive
-
-## Common Issues to Watch For
-
-High-level issues to check (detailed rules in referenced files):
-1. Platform-specific conditionals unnecessarily used in shared code
-2. Missing AutomationId in UI test interactive elements
-3. Hardcoded values instead of constants
-4. Resource leaks and missing disposal
-5. Async void methods (should be async Task except event handlers)
-6. Generic exception catching instead of specific exceptions
-7. Missing null checks
-8. Incorrect PublicAPI.Unshipped.txt entries
-9. Multiple test categories (should be ONE per test)
-10. Missing PR description template note about testing builds
-11. Auto-generated files committed
-
-## Final Notes
-
-Your goal is to help maintain the high quality of the .NET MAUI codebase while fostering a welcoming community. Every review is an opportunity to:
-- Prevent bugs from reaching users
-- Improve code quality and maintainability
-- Educate contributors on best practices
-- Build relationships within the community
-
-Be thorough, be kind, and help make .NET MAUI better with every contribution.
+**See instruction files above for complete details.**
+```
\ No newline at end of file
diff --git a/.github/instructions/appium-control.instructions.md b/.github/instructions/appium-control.instructions.md
index 714706dfc372..4d4e7b969f85 100644
--- a/.github/instructions/appium-control.instructions.md
+++ b/.github/instructions/appium-control.instructions.md
@@ -6,6 +6,12 @@ description: "Quick reference for creating standalone Appium control scripts for
Create standalone C# scripts for manual Appium-based debugging and exploration of .NET MAUI apps. Use these when you need direct control outside of automated tests.
+**🚨 CRITICAL: Appium is the ONLY way to interact with device UI**
+
+- ✅ **ALWAYS use Appium** for tapping, swiping, finding elements, rotating device, etc.
+- ❌ **NEVER use** `adb shell input tap`, `adb shell input swipe`, or coordinate-based commands
+- **Why**: Appium provides reliable element location, proper waits, and cross-device compatibility
+
**Common Command Patterns**: For UDID extraction, device boot, and build patterns, see [Common Testing Patterns](common-testing-patterns.md).
## When to Use
@@ -15,6 +21,7 @@ Create standalone C# scripts for manual Appium-based debugging and exploration o
- **Investigation** - Reproduce issues or explore edge cases
- **Learning** - Understand how Appium interacts with MAUI apps
- **Prototyping** - Test Appium interactions before creating full UI tests
+- **PR validation** - Testing PRs that affect UI behavior
**Not for automated testing** - For automated UI tests, use the established test infrastructure in `src/Controls/tests/`.
@@ -255,6 +262,62 @@ dotnet run yourscript.cs
**Complete workflow:** See [Quick Start with Sandbox App](#quick-start-with-sandbox-app) above for full end-to-end example.
+## ❌ Wrong vs ✅ Right Approach
+
+### Opening a Flyout Menu
+
+**❌ WRONG - Using ADB commands (brittle, unreliable)**:
+```bash
+# DON'T DO THIS - coordinates are device-specific and unreliable
+adb shell input tap 100 100 # Guess where hamburger menu is
+sleep 2 # Hope it opened
+```
+
+**✅ RIGHT - Using Appium (reliable, verifiable)**:
+```csharp
+// Find the hamburger menu by its accessibility properties
+var flyoutButton = driver.FindElement(
+ MobileBy.XPath("//android.widget.ImageButton[@content-desc='Open navigation drawer']")
+);
+flyoutButton.Click();
+
+// Verify it actually opened
+var flyoutItems = driver.FindElements(MobileBy.XPath("//android.widget.TextView[contains(@text, 'Item')]"));
+Console.WriteLine($"Flyout opened with {flyoutItems.Count} items");
+```
+
+### Rotating Device
+
+**❌ WRONG - Using simctl/ADB**:
+```bash
+# DON'T DO THIS - doesn't guarantee app orientation changed
+adb shell content insert --uri content://settings/system --bind name:s:user_rotation --bind value:i:1
+```
+
+**✅ RIGHT - Using Appium**:
+```csharp
+// Appium handles rotation properly and waits for completion
+driver.Orientation = ScreenOrientation.Landscape;
+
+// Verify rotation succeeded
+if (driver.Orientation != ScreenOrientation.Landscape)
+{
+ Console.WriteLine("❌ Rotation failed!");
+}
+```
+
+### Taking Screenshots
+
+**✅ BOTH are acceptable** (Appium preferred for consistency):
+```csharp
+// Appium (preferred - works cross-platform)
+var screenshot = driver.GetScreenshot();
+screenshot.SaveAsFile("/tmp/screenshot.png");
+
+// ADB (acceptable for Android-only scenarios)
+// adb exec-out screencap -p > screenshot.png
+```
+
## Common Appium Operations
### Finding and Interacting with Elements
@@ -349,7 +412,7 @@ For Shell-specific testing patterns (e.g., opening flyouts), see [UI Tests Instr
**"Device not found" (Android)**
- Verify DEVICE_UDID is set: `echo $DEVICE_UDID`
- List devices: `adb devices`
-- Start emulator via Android Studio or: `emulator -avd [avd-name]`
+- Start emulator: See [Common Testing Patterns: Android Emulator Startup](common-testing-patterns.md#android-emulator-startup-with-error-checking) for the correct background daemon pattern
**"Appium server keeps stopping"**
- Check if port 4723 is already in use: `lsof -i :4723`
diff --git a/.github/instructions/common-testing-patterns.md b/.github/instructions/common-testing-patterns.md
index 1aeb8f26a80e..36a3b15e6218 100644
--- a/.github/instructions/common-testing-patterns.md
+++ b/.github/instructions/common-testing-patterns.md
@@ -108,7 +108,7 @@ echo "Simulator is booted and ready"
### Android Emulator Startup with Error Checking
-**Used in**: Investigation work
+**Used in**: PR reviews, investigation work
**Pattern**:
```bash
@@ -117,11 +117,20 @@ pkill -9 qemu-system-x86_64 2>/dev/null || true
pkill -9 emulator 2>/dev/null || true
sleep 2
-# Restart adb server
-adb kill-server && sleep 1 && adb start-server && sleep 2
+# CRITICAL: Start emulator as background daemon that survives session end
+# Use subshell with & to fully detach from current session
+cd $ANDROID_HOME/emulator && (./emulator -avd Pixel_9 -no-snapshot-load -no-audio -no-boot-anim > /tmp/emulator.log 2>&1 &)
-# Start emulator (must run from SDK emulator directory to find dependencies)
-cd $ANDROID_HOME/emulator && ./emulator -avd Nexus_5X_API_30 -no-snapshot-load -no-audio -no-boot-anim &
+# Wait a moment for process to start
+sleep 3
+
+# Verify emulator process started
+EMULATOR_PID=$(ps aux | grep "qemu.*Pixel_9" | grep -v grep | awk '{print $2}')
+if [ -z "$EMULATOR_PID" ]; then
+ echo "❌ ERROR: Emulator failed to start"
+ exit 1
+fi
+echo "✅ Emulator started as background daemon (PID: $EMULATOR_PID)"
# Wait for device to appear
echo "Waiting for device to appear..."
@@ -151,10 +160,37 @@ echo "✅ Emulator ready: $DEVICE_UDID (API $API_LEVEL)"
**When to use**: Starting Android emulator for testing
-**Critical detail**: The emulator command must be run from `$ANDROID_HOME/emulator` directory. Running from other directories causes "Qt library not found" and "qemu-system not found" errors.
+**Why this pattern is critical**:
+
+The subshell `()` with `&` pattern is essential for emulator persistence:
+- **Problem**: Using `mode="async"` attaches the emulator to the bash session, causing it to be killed when the session ends
+- **Root cause**: Background processes attached to sessions are terminated during cleanup, even with `nohup`
+- **Solution**: Subshell `()` creates a new process group that's detached from the current session
+- **Result**: Emulator persists even when AI agent finishes responding or sessions end
+
+**Wrong approach (emulator dies)**:
+```bash
+# DON'T DO THIS - emulator will be killed when session ends
+bash --mode=async ./emulator -avd Pixel_9 &
+```
+
+**Correct approach (emulator persists)**:
+```bash
+# Subshell with & fully detaches the process
+cd $ANDROID_HOME/emulator && (./emulator -avd Pixel_9 ... &)
+```
+
+**Critical details**:
+- The emulator command must be run from `$ANDROID_HOME/emulator` directory. Running from other directories causes "Qt library not found" and "qemu-system not found" errors
+- **Use subshell `()` with `&`** to start emulator as true background daemon that persists after bash session ends
+- **NEVER use `adb kill-server`** - This disconnects ALL active ADB connections and causes emulators to lose connection. Almost never necessary
+- **NEVER use `mode="async"` for emulators** - Processes will be terminated when the session ends
+- **Check first**: Run `adb devices` before starting - if device is already visible, no action needed
**Available emulators**: List with `emulator -list-avds`
+**To verify persistence**: After starting emulator, note the PID, finish the current task, then check if the process still exists with `ps aux | grep `
+
---
## 3. Build Patterns
diff --git a/.github/instructions/issue-resolver-agent/core-workflow.md b/.github/instructions/issue-resolver-agent/core-workflow.md
new file mode 100644
index 000000000000..04e123aa8159
--- /dev/null
+++ b/.github/instructions/issue-resolver-agent/core-workflow.md
@@ -0,0 +1,323 @@
+# Core Workflow for Issue Resolution
+
+## ⏱️ TIME AND THOROUGHNESS
+
+**CRITICAL: You have unlimited time. Never skip reproduction or testing due to time concerns.**
+
+- ✅ **DO**: Take as much time as needed to thoroughly reproduce and fix the issue
+- ✅ **DO**: Test multiple scenarios and edge cases, even if it takes hours
+- ✅ **DO**: Investigate root causes deeply, don't just patch symptoms
+- ✅ **DO**: Continue working until the issue is fully resolved with proper tests
+- ❌ **DON'T**: Rush to implementation without proper reproduction
+- ❌ **DON'T**: Skip writing tests because "it works in the Sandbox"
+- ❌ **DON'T**: Submit incomplete solutions
+
+**The user will stop you when they want you to stop. Until then, keep investigating and fixing.**
+
+## ⚡ MANDATORY FIRST STEPS
+
+**Before starting issue resolution, complete these steps IN ORDER:**
+
+1. **Read Required Files**:
+ - `.github/copilot-instructions.md` - General coding standards
+ - `.github/instructions/common-testing-patterns.md` - Command patterns with error checking
+ - `.github/instructions/instrumentation.instructions.md` - Testing patterns
+ - Issue-specific instruction files if applicable (SafeArea, UITests, Templates)
+
+2. **Analyze the Issue**:
+ - Read the issue description thoroughly
+ - Check for reproduction steps provided by the reporter
+ - Review any attached screenshots, code samples, or logs
+ - Search for related or duplicate issues
+ - Check if there are existing PRs attempting to fix this
+
+3. **Begin Resolution Workflow**: Follow the thorough workflow below
+
+**If you skip any of these steps, your resolution is incomplete.**
+
+## Core Philosophy: Reproduce, Understand, Fix, Test
+
+**CRITICAL PRINCIPLE**: You are NOT just a bug fixer - you are a problem solver who deeply understands issues before implementing solutions.
+
+**Your Workflow**:
+1. 📖 **Analyze the issue report** - Understand what's broken and why it matters
+2. 🔍 **Reproduce the issue** - Create test case in Sandbox app that demonstrates the problem
+3. 🧪 **Investigate root cause** - Use instrumentation and debugging to understand WHY it fails
+4. 💡 **Design solution** - Plan the fix, considering edge cases and platform differences
+5. ⚙️ **Implement fix** - Write the code changes in the appropriate files
+6. ✅ **Test thoroughly** - Verify fix works, doesn't break other scenarios, handles edge cases
+7. 📝 **Write UI tests** - Create automated tests in TestCases.HostApp/Shared.Tests
+8. 📤 **Submit PR** - Create PR with fix, tests, and documentation
+
+**Why this matters**: Many "fixes" fail because they address symptoms without understanding root causes, miss edge cases, or break other scenarios. Your deep investigation prevents regressions.
+
+## Issue Resolution Workflow
+
+### Step 1: Analyze Issue Report
+
+**Understand the problem:**
+- What is the expected behavior?
+- What is the actual (broken) behavior?
+- Which platforms are affected?
+- What version of MAUI is affected?
+- Is this a regression (worked before) or new bug?
+
+**Gather context:**
+- Read all comments on the issue
+- Check linked PRs or related issues
+- Look for user-provided code samples
+- Review screenshots or videos if provided
+
+**Initial assessment:**
+- Is this actually a bug or expected behavior?
+- Is the issue description clear enough to reproduce?
+- Do you need more information from the reporter?
+
+### Step 2: Reproduce the Issue
+
+**Critical**: You MUST reproduce the issue before attempting to fix it.
+
+1. **Create test case in Sandbox app** (`src/Controls/samples/Controls.Sample.Sandbox/`)
+2. **Follow reporter's reproduction steps** exactly as described
+3. **Add instrumentation** to capture measurements and behavior
+4. **Verify the bug exists** - confirm you see the same broken behavior
+5. **Document reproduction** - capture console output, screenshots, measurements
+
+**If you cannot reproduce:**
+- Try different platforms (iOS, Android, Windows, Mac)
+- Try different scenarios or edge cases
+- Check if it's version-specific
+- Ask for clarification from the reporter
+
+**Template for reproduction confirmation:**
+```markdown
+## ✅ Issue Reproduced
+
+**Platform**: iOS 18.0 (iPhone 15 Pro Simulator)
+**MAUI Version**: net10.0
+
+**Reproduction Steps**:
+1. [Exact steps you followed]
+2. [...]
+
+**Observed Behavior**:
+```
+[Console output or measurements showing the bug]
+```
+
+**Expected Behavior**:
+[What should happen instead]
+
+**Screenshots**: [If applicable]
+```
+
+### Step 3: Investigate Root Cause
+
+**Don't just fix symptoms - understand WHY the bug exists:**
+
+1. **Add detailed instrumentation** to track execution flow
+2. **Examine platform-specific code** (iOS, Android, Windows, Mac)
+3. **Check recent changes** - was this introduced by a recent PR?
+4. **Review related code** - what else might be affected?
+5. **Test edge cases** - when does it fail vs. when does it work?
+
+**Use instrumentation patterns from `.github/instructions/instrumentation.instructions.md`**
+
+**Questions to answer:**
+- Where in the code does the failure occur?
+- What is the sequence of events leading to the failure?
+- Is it platform-specific or cross-platform?
+- Are there existing workarounds or related fixes?
+
+### Step 4: Design Solution
+
+**Before writing code, plan your approach:**
+
+1. **Identify the minimal fix** - smallest change that solves the root cause
+2. **Consider platform differences** - does the fix need platform-specific code?
+3. **Think about edge cases** - what scenarios might break with your fix?
+4. **Check for breaking changes** - will this affect existing user code?
+5. **Plan tests** - what automated tests will verify this fix?
+
+**Validation checkpoint** (optional but recommended for complex fixes):
+- Show your planned approach to the user
+- Explain what you'll change and why
+- Get confirmation before implementing
+
+### Step 5: Implement Fix
+
+**Write the code changes:**
+
+1. **Modify the appropriate files** in `src/Core/`, `src/Controls/`, or `src/Essentials/`
+2. **Follow .NET MAUI coding standards** from `.github/copilot-instructions.md`
+3. **Add platform-specific code** in correct folders (`Android/`, `iOS/`, `Windows/`, `MacCatalyst/`)
+4. **Add XML documentation** for any new public APIs
+5. **Format code** with `dotnet format` before committing
+
+**Critical considerations:**
+- Keep changes minimal and focused
+- Don't refactor unrelated code in the same PR
+- Ensure null safety and proper error handling
+- Follow existing patterns in the codebase
+
+### Step 6: Test Thoroughly
+
+**Verify your fix works:**
+
+1. **Test in Sandbox app** - Original issue scenario works correctly
+2. **Test edge cases** - Empty state, null values, rapid changes, etc.
+3. **Test on all affected platforms** - iOS, Android, Windows, Mac
+4. **Test WITH and WITHOUT the fix** - Confirm fix actually solves the problem
+5. **Test related scenarios** - Ensure fix doesn't break similar functionality
+
+**Use same testing approach as pr-reviewer:**
+- Modify Sandbox app with instrumentation
+- Capture measurements before and after fix
+- Document test results with actual data
+
+### Step 7: Write UI Tests
+
+**Create automated tests for the fix:**
+
+1. **Create test page** in `src/Controls/tests/TestCases.HostApp/Issues/IssueXXXXX.xaml`
+2. **Create NUnit test** in `src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/IssueXXXXX.cs`
+3. **Follow UI testing guidelines** from `.github/instructions/uitests.instructions.md`
+
+**Test should:**
+- Reproduce the original bug scenario
+- Verify the fix resolves it
+- Test at least one edge case
+- Use `VerifyScreenshot()` for visual validation when appropriate
+
+See UITesting-Guide.md for complete test creation details.
+
+### Step 8: Submit PR
+
+**Create a pull request with your fix:**
+
+1. **PR Title Format**: `[Issue-Resolver] Fix #XXXXX - `
+
+ **Structure**:
+ - **Prefix**: `[Issue-Resolver]` (REQUIRED - identifies agent-created PRs)
+ - **Issue reference**: `Fix #XXXXX` (links and auto-closes the issue when merged)
+ - **Description**: Brief, clear summary of what was fixed
+
+ **Examples**:
+ - `[Issue-Resolver] Fix #12345 - CollectionView RTL padding incorrect on iOS`
+ - `[Issue-Resolver] Fix #67890 - Label text truncation with SafeArea enabled`
+ - `[Issue-Resolver] Fix #11111 - Entry cursor position wrong in RTL mode on Android`
+
+ **Why the prefix matters**:
+ - Helps maintainers identify PRs created by the issue-resolver agent
+ - Enables tracking of agent effectiveness and contribution patterns
+ - Distinguishes from community-contributed PRs for metrics and triage
+
+ **Common mistakes to avoid**:
+ - ❌ `Fix #12345 - CollectionView padding` (missing [Issue-Resolver] prefix)
+ - ❌ `[Issue-Resolver] CollectionView RTL fix` (missing "Fix #XXXXX" reference)
+ - ❌ `[Issue-Resolver] Fix #12345` (missing description)
+ - ✅ `[Issue-Resolver] Fix #12345 - CollectionView RTL padding incorrect on iOS` (correct!)
+
+2. **PR Description** must include:
+ ```markdown
+ Fixes #XXXXX
+
+ ## Description
+ [Brief description of the issue and fix]
+
+ ## Root Cause
+ [Explanation of why the bug existed]
+
+ ## Solution
+ [Explanation of how the fix resolves it]
+
+ ## Testing
+ **Reproduction verified on**: [Platform(s)]
+
+ **Before fix**:
+ ```
+ [Console output or measurements showing bug]
+ ```
+
+ **After fix**:
+ ```
+ [Console output or measurements showing fix works]
+ ```
+
+ **Edge cases tested**:
+ - [List edge cases you tested]
+
+ ## Test Coverage
+ - ✅ UI test added: `Tests/Issues/IssueXXXXX.cs`
+ - ✅ Test page added: `TestCases.HostApp/Issues/IssueXXXXX.xaml`
+
+ ## Breaking Changes
+ [None / List any breaking changes]
+
+ ## Notes
+ [Any additional context for reviewers]
+ ```
+
+3. **Link the issue** - Use `Fixes #XXXXX` in description
+
+4. **Request review** from appropriate maintainers
+
+## Core Responsibilities
+
+1. **Issue Investigation**: Deeply understand reported problems through reproduction and analysis
+2. **Root Cause Analysis**: Identify WHY bugs exist, not just symptoms
+3. **Solution Implementation**: Write minimal, correct fixes that address root causes
+4. **Comprehensive Testing**: Verify fixes work across platforms and edge cases
+5. **Test Automation**: Create UI tests to prevent regressions
+6. **Documentation**: Update docs if the fix changes public behavior
+
+## Quality Standards
+
+**Before submitting your PR, verify:**
+
+- [ ] Issue reproduced and root cause identified
+- [ ] Fix implemented with minimal code changes
+- [ ] Fix tested on all affected platforms
+- [ ] Edge cases tested and handled
+- [ ] UI tests added (TestCases.HostApp + TestCases.Shared.Tests)
+- [ ] Code formatted with `dotnet format`
+- [ ] No breaking changes (or clearly documented if necessary)
+- [ ] PR description complete with before/after evidence
+- [ ] Issue linked in PR description
+
+## Common Pitfalls to Avoid
+
+1. **Fixing without reproducing** - Always reproduce first
+2. **Treating symptoms not causes** - Understand WHY before implementing
+3. **Incomplete testing** - Test edge cases and platforms
+4. **Missing tests** - Every fix needs automated tests
+5. **Breaking changes** - Avoid unless absolutely necessary
+6. **Unclear PR descriptions** - Document before/after thoroughly
+7. **Over-engineering** - Keep fixes minimal and focused
+8. **Ignoring platform differences** - Test on all affected platforms
+9. **Not checking for regressions** - Verify related scenarios still work
+10. **Skipping documentation updates** - Update docs if behavior changes
+
+## When to Ask for Help
+
+**Pause and ask for guidance if:**
+- Cannot reproduce the issue after multiple attempts
+- Root cause is unclear or extremely complex
+- Solution requires significant architectural changes
+- Breaking changes seem necessary
+- Multiple approaches seem equally valid
+- Build errors persist after troubleshooting
+- Issue appears to be in platform SDK, not MAUI code
+
+**It's better to ask than to guess wrong.**
+
+## Final Notes
+
+Your goal is to make .NET MAUI better by:
+- Fixing real problems that affect users
+- Preventing regressions through comprehensive testing
+- Understanding codebases deeply through investigation
+- Maintaining high code quality standards
+- Building trust with the community through reliable fixes
+
+Every issue you resolve makes MAUI more stable and reliable for thousands of developers.
diff --git a/.github/instructions/issue-resolver-agent/error-handling.md b/.github/instructions/issue-resolver-agent/error-handling.md
new file mode 100644
index 000000000000..a6fa668207aa
--- /dev/null
+++ b/.github/instructions/issue-resolver-agent/error-handling.md
@@ -0,0 +1,592 @@
+# Error Handling and Troubleshooting
+
+## Reproduction Failures
+
+### Issue Does Not Reproduce
+
+**Common reasons and solutions:**
+
+#### 1. Platform Differences
+
+**Symptom**: Issue reproduces on reporter's device but not in simulator/emulator
+
+**Diagnosis:**
+```bash
+# Check what device/OS reporter used
+# Compare to your test environment
+```
+
+**Solutions:**
+
+**iOS Version Mismatch:**
+```bash
+# Reporter used iOS 17.1, you're testing iOS 18.0
+# Try older simulator if available
+
+# List available iOS versions
+xcrun simctl list runtimes | grep iOS
+
+# Create simulator with specific iOS version if available
+xcrun simctl create "iPhone 15 iOS 17.1" \
+ "com.apple.CoreSimulator.SimDeviceType.iPhone-15" \
+ "com.apple.CoreSimulator.SimRuntime.iOS-17-1"
+```
+
+**Android API Level Mismatch:**
+```bash
+# Reporter used Android 12 (API 31), you're testing Android 14 (API 34)
+# Try emulator with matching API level
+
+# List available system images
+sdkmanager --list | grep system-images
+
+# Create emulator with specific API level
+avdmanager create avd -n Android31 -k "system-images;android-31;google_apis;x86_64"
+```
+
+**Real Device vs Simulator:**
+- Some issues only reproduce on physical devices
+- Request access to physical device if available
+- Note in PR that physical device testing needed
+
+#### 2. Timing/Race Conditions
+
+**Symptom**: Issue is intermittent or timing-dependent
+
+**Solutions:**
+
+**Add delays to test different timing:**
+```csharp
+// Try different delays to expose race condition
+private async void OnButtonClicked(object sender, EventArgs e)
+{
+ await Task.Delay(100); // Try 0, 50, 100, 500ms
+
+ // Rest of code
+}
+```
+
+**Check for async/await issues:**
+```csharp
+// BAD: Fire and forget
+UpdateSomethingAsync(); // Race condition
+
+// GOOD: Proper await
+await UpdateSomethingAsync();
+```
+
+**Add instrumentation to capture timing:**
+```csharp
+Console.WriteLine($"[{DateTime.Now:HH:mm:ss.fff}] Event triggered");
+```
+
+#### 3. Data/State Dependencies
+
+**Symptom**: Issue needs specific data or app state
+
+**Solutions:**
+
+**Vary the test data:**
+```csharp
+// Try different data scenarios
+TestCollection.ItemsSource = new[] { "A" }; // Single item
+TestCollection.ItemsSource = new[] { "A", "B", "C" }; // Few items
+TestCollection.ItemsSource = Enumerable.Range(1, 100).Select(x => $"Item {x}"); // Many items
+TestCollection.ItemsSource = new string[0]; // Empty
+TestCollection.ItemsSource = null; // Null
+```
+
+**Test different property combinations:**
+```csharp
+// Try different configurations
+control.Property1 = "Value1";
+control.Property2 = true;
+control.Property3 = 42;
+
+// vs
+control.Property1 = null;
+control.Property2 = false;
+control.Property3 = 0;
+```
+
+**Test different page lifecycles:**
+```csharp
+// Issue might need navigation
+await Navigation.PushAsync(new TestPage());
+await Task.Delay(500);
+await Navigation.PopAsync();
+```
+
+#### 4. Incomplete Reproduction Steps
+
+**Symptom**: Issue report doesn't include all necessary steps
+
+**Action**: Ask for clarification on the original issue:
+
+```markdown
+@[original-reporter] I'm attempting to reproduce this issue but need some additional information:
+
+1. What exact device/OS version are you using?
+2. Does this happen immediately or after specific actions?
+3. Can you provide a minimal code sample that demonstrates the issue?
+4. Are there any specific properties/settings required?
+5. Does this happen in a new project or only in your specific app?
+
+This will help me create an accurate fix. Thank you!
+```
+
+### When to Document "Cannot Reproduce"
+
+If you genuinely cannot reproduce the issue after thorough attempts:
+
+**Document your efforts:**
+```markdown
+## Investigation Results
+
+**Attempted reproduction on:**
+- iOS 18.0 Simulator (iPhone 15 Pro)
+- Android 14.0 Emulator (Pixel 7)
+- Windows 11
+
+**Variations tested:**
+- Different data sizes (empty, 1 item, 100 items)
+- Different property combinations (FlowDirection, Padding, Margin)
+- Different timing (immediate, delayed, rapid changes)
+- Different page lifecycles (fresh load, navigation, modal)
+
+**Result**: Unable to reproduce the reported behavior
+
+**Next steps:**
+- Requested additional information from reporter (see comment #123)
+- May need physical device testing
+- May be specific to reporter's environment
+
+Waiting for more details before proceeding.
+```
+
+## Build Errors During Fix Development
+
+### Common Build Errors and Solutions
+
+#### 1. PublicAPI.Unshipped.txt Errors
+
+**Error:**
+```
+error RS0016: Symbol 'Microsoft.Maui.Controls.CollectionView.UpdateLayoutDirection()'
+is not marked as public API
+```
+
+**Solution:**
+
+**Don't disable analyzer or suppress:**
+```csharp
+// ❌ BAD: Hiding the problem
+#pragma warning disable RS0016
+```
+
+**Fix the PublicAPI.Unshipped.txt file:**
+
+1. **Locate the file** for the affected project:
+ ```bash
+ find src/Core -name "PublicAPI.Unshipped.txt"
+ ```
+
+2. **Add the missing API** to the file:
+ ```
+ Microsoft.Maui.Controls.CollectionView.UpdateLayoutDirection(Microsoft.Maui.FlowDirection) -> void
+ ```
+
+3. **Or use `dotnet format analyzers`**:
+ ```bash
+ dotnet format analyzers Microsoft.Maui.sln
+ ```
+
+4. **If still having issues, revert and re-add:**
+ ```bash
+ # Revert all PublicAPI.Unshipped.txt changes
+ git checkout -- **/PublicAPI.Unshipped.txt
+
+ # Re-run format analyzers
+ dotnet format analyzers Microsoft.Maui.sln
+ ```
+
+See "PublicAPI.Unshipped.txt File Management" in `.github/copilot-instructions.md` for more details.
+
+#### 2. Platform-Specific Compilation Errors
+
+**Error:**
+```
+error CS0246: The type or namespace name 'UIKit' could not be found
+```
+
+**Solution**: Add proper conditional compilation:
+
+```csharp
+#if IOS || MACCATALYST
+using UIKit;
+
+internal static void UpdateLayoutDirection(this UICollectionViewCompositionalLayout layout)
+{
+ // iOS-specific code
+}
+#endif
+```
+
+**Verify targeting is correct:**
+```xml
+
+net10.0-android;net10.0-ios;net10.0-maccatalyst
+```
+
+#### 3. Missing Assembly References
+
+**Error:**
+```
+error CS0012: The type 'SomeType' is defined in an assembly that is not referenced
+```
+
+**Solution**: Add package reference if needed:
+
+```bash
+# Find which package contains the type
+dotnet add package
+
+# Or check existing references
+grep -r "SomeType" src/Core/src/Core.csproj
+```
+
+#### 4. Null Reference Warnings (Nullable Context)
+
+**Error:**
+```
+warning CS8602: Dereference of a possibly null reference
+```
+
+**Solution**: Add proper null checks:
+
+```csharp
+// ❌ BAD: Ignoring the warning
+handler.PlatformView!.UpdateSomething(); // ! suppresses warning
+
+// ✅ GOOD: Proper null handling
+if (handler.PlatformView is not null)
+ handler.PlatformView.UpdateSomething();
+
+// OR
+handler.PlatformView?.UpdateSomething();
+```
+
+## Unexpected Behavior After Fix
+
+### Fix Doesn't Work as Expected
+
+**Symptom**: Your fix compiles and runs, but doesn't actually resolve the issue
+
+**Debugging steps:**
+
+#### 1. Verify Fix Is Actually Running
+
+**Add console logging:**
+```csharp
+public static void MapFlowDirection(ICollectionViewHandler handler, ICollectionView view)
+{
+ Console.WriteLine($"[DEBUG] MapFlowDirection called: {view.FlowDirection}");
+
+ handler.PlatformView?.UpdateFlowDirection(view);
+
+ Console.WriteLine("[DEBUG] UpdateFlowDirection completed");
+}
+```
+
+**Check logs:**
+```bash
+# iOS
+xcrun simctl spawn booted log stream --predicate 'eventMessage contains "[DEBUG]"'
+
+# Android
+adb logcat | grep "\[DEBUG\]"
+```
+
+**If logging doesn't appear:**
+- Fix code isn't being called
+- Check if mapper is registered correctly
+- Verify handler is using your updated code
+
+#### 2. Verify Property Values
+
+**Check what values are actually being set:**
+```csharp
+internal static void UpdateFlowDirection(this UICollectionView view, ICollectionView collectionView)
+{
+ var attribute = collectionView.FlowDirection == FlowDirection.RightToLeft
+ ? UISemanticContentAttribute.ForceRightToLeft
+ : UISemanticContentAttribute.ForceLeftToRight;
+
+ Console.WriteLine($"[DEBUG] Setting SemanticContentAttribute: {attribute}");
+ Console.WriteLine($"[DEBUG] Current value: {view.SemanticContentAttribute}");
+
+ view.SemanticContentAttribute = attribute;
+
+ Console.WriteLine($"[DEBUG] New value: {view.SemanticContentAttribute}");
+}
+```
+
+**If values are wrong:**
+- Check enum mappings
+- Verify platform API behavior
+- Test with hardcoded values first
+
+#### 3. Check Platform API Documentation
+
+**Verify you're using the API correctly:**
+
+**iOS:**
+- Apple Developer Documentation: https://developer.apple.com/documentation/
+- UIKit reference for control you're modifying
+- Verify API is available in minimum supported iOS version
+
+**Android:**
+- Android Developer Documentation: https://developer.android.com/reference
+- Check API level requirements
+- Verify correct View class is being modified
+
+**Windows:**
+- WinUI 3 Documentation: https://docs.microsoft.com/windows/winui/
+- Check if property/method exists in WinUI 3
+
+### Fix Causes Side Effects
+
+**Symptom**: Fix resolves the issue but breaks something else
+
+**Diagnosis:**
+
+**Test related scenarios:**
+```csharp
+// If you fixed RTL padding on CollectionView
+// Test that LTR still works:
+TestCollection.FlowDirection = FlowDirection.LeftToRight;
+// Verify padding is correct
+
+// Test that other collections still work:
+var listView = new ListView { FlowDirection = FlowDirection.RightToLeft };
+// Verify ListView not affected
+```
+
+**Run existing tests:**
+```bash
+# Run all CollectionView tests
+dotnet test src/Controls/tests/TestCases.Shared.Tests/Controls.TestCases.Shared.Tests.csproj \
+ --filter "Category=CollectionView"
+
+# Check for failures
+```
+
+**Review your changes:**
+- Did you modify shared code used by multiple controls?
+- Did you change behavior for all cases, not just the bug case?
+- Did you introduce a regression?
+
+**Fix the side effect:**
+- Make your fix more specific/targeted
+- Add conditional logic to only apply fix to affected scenario
+- Revert and try alternative approach
+
+## When to Ask for Help
+
+**Don't struggle alone - ask for guidance in these situations:**
+
+### 1. Cannot Reproduce After Extensive Attempts
+
+**When:**
+- Tried all platform variations
+- Tested with different data/timing/states
+- Requested clarification from reporter
+- Still cannot see the issue
+
+**Action**: Comment on the issue:
+```markdown
+I've attempted to reproduce this issue with the following configurations:
+- [List all attempts]
+
+Unfortunately, I cannot reproduce the reported behavior. Would appreciate:
+1. Additional reproduction steps
+2. Sample project that demonstrates the issue
+3. Confirmation issue still exists in latest version
+
+@dotnet/maui-team - any suggestions for alternative approaches?
+```
+
+### 2. Root Cause Is Unclear
+
+**When:**
+- Can reproduce the issue
+- Issue behavior is confirmed
+- But don't understand WHY it's happening
+
+**Action**: Document what you know and ask:
+```markdown
+**Reproduction**: ✅ Confirmed on iOS 18.0
+
+**Observations:**
+- [What you've observed]
+- [What instrumentation showed]
+- [What you've ruled out]
+
+**Question**: The issue seems to be related to [X], but I'm not clear on why [Y]
+is causing this behavior. Could someone with more experience in [platform/control]
+provide guidance?
+```
+
+### 3. Multiple Possible Solutions
+
+**When:**
+- Have identified 2+ ways to fix the issue
+- Unsure which approach is better for MAUI architecture
+- Each has tradeoffs
+
+**Action**: Present the options:
+```markdown
+**Root cause identified**: [Explanation]
+
+**Possible solutions:**
+
+**Option 1**: [Approach A]
+- ✅ Pros: [Benefits]
+- ❌ Cons: [Drawbacks]
+
+**Option 2**: [Approach B]
+- ✅ Pros: [Benefits]
+- ❌ Cons: [Drawbacks]
+
+**Question**: Which approach aligns better with MAUI architecture patterns?
+Or is there a third option I'm not considering?
+```
+
+### 4. Fix Works But Concerned About Side Effects
+
+**When:**
+- Fix resolves the issue
+- But touches shared/core code
+- Worried about unintended consequences
+
+**Action**: Request review before PR:
+```markdown
+**Fix implemented**: [Brief description]
+
+**Concerns:**
+- Modified [shared file/method]
+- Could potentially affect [other controls]
+- Want to validate approach before creating PR
+
+**Testing done:**
+- [What you've tested]
+- [What you haven't been able to test]
+
+Could someone review the approach before I proceed with formal PR?
+
+[Link to branch or code snippet]
+```
+
+### 5. Platform API Confusion
+
+**When:**
+- Platform API behavior doesn't match documentation
+- Unexpected results from platform calls
+- API seems broken or buggy
+
+**Action**: Ask platform-specific experts:
+```markdown
+**Platform**: iOS (or Android/Windows/Mac)
+
+**API**: UICollectionViewCompositionalLayout.Configuration
+
+**Expected**: Setting ScrollDirection should [X]
+
+**Actual**: [Y happens instead]
+
+**Question**: Is this expected behavior? Is there a different API I should use?
+Or is this a platform SDK issue?
+
+**Test code:**
+```csharp
+[Your minimal test case]
+```
+```
+
+## Logging and Diagnostics
+
+### Effective Debug Logging
+
+**Structure your logs for easy filtering:**
+
+```csharp
+// Use consistent prefixes
+Console.WriteLine($"[REPRO-12345] FlowDirection changed to {value}");
+Console.WriteLine($"[REPRO-12345] Layout updated: {layout.Configuration}");
+Console.WriteLine($"[REPRO-12345] Measurements: {width}x{height}");
+
+// Grep for your specific issue
+// adb logcat | grep "REPRO-12345"
+```
+
+**Log at key decision points:**
+```csharp
+public static void MapProperty(Handler handler, IView view)
+{
+ Console.WriteLine($"[DEBUG] MapProperty called");
+
+ if (handler.PlatformView is null)
+ {
+ Console.WriteLine($"[DEBUG] PlatformView is null, returning");
+ return;
+ }
+
+ Console.WriteLine($"[DEBUG] Updating PlatformView");
+ handler.PlatformView.UpdateSomething();
+ Console.WriteLine($"[DEBUG] Update completed");
+}
+```
+
+### Common Diagnostic Patterns
+
+**Measure timing:**
+```csharp
+var sw = System.Diagnostics.Stopwatch.StartNew();
+// Operation
+sw.Stop();
+Console.WriteLine($"[PERF] Operation took {sw.ElapsedMilliseconds}ms");
+```
+
+**Capture call stacks:**
+```csharp
+Console.WriteLine($"[STACK] {Environment.StackTrace}");
+```
+
+**Dump object state:**
+```csharp
+Console.WriteLine($"[STATE] Control: {control.GetType().Name}");
+Console.WriteLine($"[STATE] Width: {control.Width}, Height: {control.Height}");
+Console.WriteLine($"[STATE] IsVisible: {control.IsVisible}");
+// etc.
+```
+
+## Recovery Strategies
+
+### Start Over vs. Pivot
+
+**When to start over:**
+- Approach is fundamentally flawed
+- Too many side effects/complications
+- Cleaner solution becomes apparent
+
+**When to pivot:**
+- Core approach is sound
+- Just need different implementation details
+- Can isolate problem to specific method/section
+
+**When to seek help:**
+- Stuck for > 2 hours on same problem
+- Multiple approaches have failed
+- Missing domain knowledge
+
+**Remember:** It's okay to ask for help. The MAUI team wants issues fixed correctly, not quickly.
diff --git a/.github/instructions/issue-resolver-agent/pr-submission.md b/.github/instructions/issue-resolver-agent/pr-submission.md
new file mode 100644
index 000000000000..4c60e12abd4b
--- /dev/null
+++ b/.github/instructions/issue-resolver-agent/pr-submission.md
@@ -0,0 +1,418 @@
+# PR Submission Guidelines
+
+## Creating the Pull Request
+
+### PR Title Format
+
+**Required format**: `[Issue-Resolver] Fix #XXXXX - `
+
+**Examples:**
+- `[Issue-Resolver] Fix #12345 - CollectionView RTL padding incorrect on iOS`
+- `[Issue-Resolver] Fix #67890 - Label text truncation with SafeArea enabled`
+- `[Issue-Resolver] Fix #11111 - Entry cursor position wrong in RTL mode`
+
+**The `[Issue-Resolver]` prefix:**
+- Identifies PRs created by the issue-resolver agent
+- Helps maintainers track agent-generated contributions
+- Distinguishes from community PRs
+
+### PR Description Template
+
+**Complete template to use:**
+
+```markdown
+Fixes #XXXXX
+
+## Description
+
+[Brief description of what the issue was and what this PR fixes]
+
+Example:
+"CollectionView was not applying correct padding in RTL mode on iOS because the compositional layout wasn't configured to respect the semantic content attribute."
+
+## Root Cause
+
+[Technical explanation of WHY the bug existed]
+
+Example:
+"The `UpdateFlowDirection` method in `CollectionViewHandler.iOS.cs` only set the `SemanticContentAttribute` on the UICollectionView itself, but UICollectionViewCompositionalLayout requires explicit configuration on the layout object to properly handle RTL scenarios. The layout continued using LTR direction regardless of the view's semantic attribute."
+
+## Solution
+
+[Explanation of HOW your fix resolves the root cause]
+
+Example:
+"Added a new extension method `UpdateLayoutDirection()` that configures the UICollectionViewCompositionalLayout's scroll direction based on FlowDirection. This method is called whenever FlowDirection changes, ensuring the layout properly mirrors content in RTL mode."
+
+**Changes made:**
+- Modified `CollectionViewHandler.iOS.cs` to update layout configuration
+- Added `UpdateLayoutDirection()` extension method
+- Updated `MapFlowDirection()` to configure both view and layout
+
+## Testing
+
+### Reproduction Verified
+
+**Platform**: iOS 18.0 (iPhone 15 Pro Simulator)
+**Build**: Debug, net10.0-ios
+
+**Before fix:**
+```
+=== STATE CAPTURE: AfterTrigger ===
+Control Bounds: {X=0 Y=0 Width=393 Height=600}
+Left Padding: 0px ❌ (Expected: 16px)
+Right Padding: 16px ❌ (Expected: 0px)
+```
+
+**After fix:**
+```
+=== STATE CAPTURE: AfterTrigger ===
+Control Bounds: {X=0 Y=0 Width=393 Height=600}
+Left Padding: 16px ✅
+Right Padding: 0px ✅
+```
+
+### Edge Cases Tested
+
+| Scenario | Result |
+|----------|--------|
+| Empty ItemsSource | ✅ No crash, handles correctly |
+| Null ItemsSource | ✅ Handles gracefully |
+| Rapid FlowDirection toggling (10x) | ✅ No flicker or incorrect state |
+| FlowDirection.MatchParent | ✅ Inherits correctly from parent |
+| With headers and footers | ✅ Padding applies to all sections |
+| While scrolling | ✅ Updates correctly without interruption |
+| Nested in ScrollView | ✅ Both controls handle RTL correctly |
+
+### Platforms Tested
+
+- ✅ iOS 18.0 (Simulator)
+- ✅ Android 14.0 (Emulator) - Verify no regression
+- ⏭️ Windows - Not affected by this iOS-specific issue
+- ⏭️ MacCatalyst - Same code path as iOS, assumed working
+
+### Related Scenarios Verified
+
+Verified these related scenarios still work correctly:
+- ✅ FlowDirection on ListView
+- ✅ FlowDirection on Grid layouts
+- ✅ Nested RTL controls
+- ✅ CollectionView with different ItemsLayout types
+
+## Test Coverage
+
+**UI Tests Added:**
+- ✅ Test page: `src/Controls/tests/TestCases.HostApp/Issues/Issue12345.xaml`
+- ✅ NUnit test: `src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue12345.cs`
+
+**Test validates:**
+- CollectionView displays with correct RTL padding
+- Padding values are swapped correctly (left/right)
+- Screenshot verification confirms visual correctness
+
+## Breaking Changes
+
+**None** - This fix is purely a bug fix with no API changes or behavior changes to correct functionality.
+
+[OR if there are breaking changes:]
+
+**⚠️ Breaking Changes:**
+- [List any breaking changes]
+- [Explain why they are necessary]
+- [Provide migration guidance]
+
+## Additional Notes
+
+[Any other context for reviewers]
+
+Examples:
+- "This fix only affects iOS. Android already handles this correctly."
+- "Considered alternative approach X, but rejected because Y."
+- "This may need backporting to release/X.X branch."
+```
+
+### Writing UI Tests
+
+**Required for every fix**: Create automated tests to prevent regressions.
+
+#### Step 1: Create Test Page
+
+**File**: `src/Controls/tests/TestCases.HostApp/Issues/Issue12345.xaml`
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**File**: `src/Controls/tests/TestCases.HostApp/Issues/Issue12345.xaml.cs`
+
+```csharp
+using System.Collections.ObjectModel;
+using Microsoft.Maui.Controls;
+
+namespace Maui.Controls.Sample.Issues
+{
+ [Issue(IssueTracker.Github, 12345, "CollectionView RTL padding incorrect",
+ PlatformAffected.iOS)]
+ public partial class Issue12345 : ContentPage
+ {
+ public ObservableCollection Items { get; set; }
+
+ public Issue12345()
+ {
+ InitializeComponent();
+
+ Items = new ObservableCollection
+ {
+ "Item 1",
+ "Item 2",
+ "Item 3"
+ };
+
+ BindingContext = this;
+ }
+ }
+}
+```
+
+#### Step 2: Create NUnit Test
+
+**File**: `src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue12345.cs`
+
+```csharp
+using NUnit.Framework;
+using UITest.Appium;
+using UITest.Core;
+
+namespace Microsoft.Maui.TestCases.Tests.Issues
+{
+ public class Issue12345 : _IssuesUITest
+ {
+ public Issue12345(TestDevice device) : base(device)
+ {
+ }
+
+ public override string Issue => "CollectionView RTL padding incorrect on iOS";
+
+ [Test]
+ [Category(UITestCategories.CollectionView)]
+ public void CollectionViewRTLPaddingShouldBeCorrect()
+ {
+ // Wait for collection to load
+ App.WaitForElement("TestCollection");
+
+ // Verify the fix with screenshot
+ // Screenshot will show RTL padding is correctly applied
+ VerifyScreenshot();
+ }
+ }
+}
+```
+
+**Key points for UI tests:**
+- Use `[Issue]` attribute with issue number and description
+- Add proper `AutomationId` to all interactive elements
+- Use `VerifyScreenshot()` for visual validation
+- Add to appropriate `[Category]` (CollectionView, Label, Entry, etc.)
+- Keep test simple and focused on the specific issue
+
+See `.github/instructions/uitests.instructions.md` for comprehensive UI testing guidance.
+
+### Code Formatting
+
+**Before committing, format the code:**
+
+```bash
+# Format the entire solution
+dotnet format Microsoft.Maui.sln --no-restore --exclude Templates/src --exclude-diagnostics CA1822
+
+# Verify no formatting issues
+dotnet format Microsoft.Maui.sln --verify-no-changes --no-restore --exclude Templates/src
+```
+
+### Creating the PR
+
+**Step-by-step process:**
+
+1. **Clean up unrelated changes before committing:**
+
+ **Remove changes to files not related to your fix:**
+ - Revert any modifications to `MainPage.xaml` and `MainPage.xaml.cs` (used for local testing)
+ - Revert changes to any other test/sample files you used during reproduction
+ - Remove any debug logging or temporary instrumentation added during investigation
+
+ **Check what's staged:**
+ ```bash
+ git status
+ git diff
+ ```
+
+ **Revert specific unrelated files:**
+ ```bash
+ # Revert Sandbox MainPage files
+ git checkout -- src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml
+ git checkout -- src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml.cs
+
+ # Or use git restore (newer syntax)
+ git restore src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml
+ git restore src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml.cs
+ ```
+
+ **Your PR should only include:**
+ - ✅ The actual fix (modified source files)
+ - ✅ UI test files (TestCases.HostApp/Issues/IssueXXXXX.*)
+ - ✅ NUnit test files (TestCases.Shared.Tests/Tests/Issues/IssueXXXXX.cs)
+ - ✅ Screenshot baselines (if using VerifyScreenshot)
+ - ✅ PublicAPI.Unshipped.txt updates (if you added public APIs)
+ - ❌ NOT: MainPage.xaml/cs changes from Sandbox testing
+ - ❌ NOT: Temporary debug code or console logging
+ - ❌ NOT: Auto-generated files (cgmanifest.json, templatestrings.json)
+
+2. **Commit your changes:**
+ ```bash
+ git add .
+ git commit -m "[Issue-Resolver] Fix #12345 - CollectionView RTL padding"
+ ```
+
+3. **Push to your fork:**
+ ```bash
+ git push origin fix-issue-12345
+ ```
+
+4. **Open PR on GitHub:**
+ - Navigate to https://github.com/dotnet/maui
+ - Click "Pull requests" → "New pull request"
+ - Select your branch
+ - Fill in the complete PR description and title template
+
+5. **Add required note at top of description:**
+ ```markdown
+
+ > [!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!
+ ```
+
+6. **Link the issue:**
+ - Use `Fixes #12345` in PR description
+ - GitHub will automatically link and close the issue when PR merges
+
+7. **Request review:**
+ - Tag appropriate maintainers if known
+ - Wait for CI checks to pass
+ - Respond to review feedback promptly
+
+## PR Checklist
+
+**Before submitting, verify:**
+
+- [ ] PR title follows format: `[Issue-Resolver] Fix #XXXXX - `
+- [ ] PR description is complete with all required sections
+- [ ] Required note added at top of PR description
+- [ ] Issue is linked with `Fixes #XXXXX`
+- [ ] Root cause explained clearly
+- [ ] Solution approach documented
+- [ ] Before/after test results included
+- [ ] Edge cases documented
+- [ ] All affected platforms tested
+- [ ] UI tests created (TestCases.HostApp + Shared.Tests)
+- [ ] Code formatted with `dotnet format`
+- [ ] No breaking changes (or justified and documented)
+- [ ] PublicAPI.Unshipped.txt updated if public APIs changed
+- [ ] XML documentation added for new public APIs
+- [ ] No auto-generated files committed (cgmanifest.json, templatestrings.json)
+
+## After PR Submission
+
+**Monitor your PR:**
+
+1. **Watch for CI failures:**
+ - Build errors → Fix and push update
+ - Test failures → Investigate and fix
+ - Format issues → Run `dotnet format` and push
+
+2. **Respond to review comments:**
+ - Address feedback promptly
+ - Explain your reasoning when needed
+ - Make requested changes
+ - Re-request review after updates
+
+3. **Update based on feedback:**
+ - Make code changes as requested
+ - Add additional tests if needed
+ - Update documentation
+ - Push updates to the same branch
+
+4. **Communicate with issue reporter:**
+ - Let them know PR is submitted
+ - Ask them to test the PR build when available
+ - Thank them for reporting the issue
+
+## Common PR Mistakes to Avoid
+
+❌ **Incomplete PR description**
+- Missing root cause explanation
+- No before/after test results
+- Missing edge case documentation
+
+❌ **Missing tests**
+- No UI tests added
+- Only tested happy path
+- Didn't test on all affected platforms
+
+❌ **Too many changes**
+- Unrelated refactoring included
+- Multiple issues fixed in one PR
+- Changed code formatting throughout unrelated files
+
+❌ **Not linking the issue**
+- Forgot `Fixes #XXXXX` in description
+- Issue not automatically closed when merged
+
+❌ **Breaking changes without justification**
+- Changed public API behavior without explanation
+- No migration guidance provided
+
+❌ **Ignoring CI failures**
+- Submitted PR with known build errors
+- Didn't check test results
+
+## Example of Excellent PR
+
+**Title**: `[Issue-Resolver] Fix #12345 - CollectionView RTL padding incorrect on iOS`
+
+**Description**: Complete, with all sections filled in, root cause explained, solution documented, comprehensive testing results, UI tests added
+
+**Changes**: Minimal, focused only on fixing the specific issue
+
+**Tests**: Both HostApp page and NUnit test added, edge cases covered
+
+**Documentation**: XML docs added for any new public methods
+
+**Result**: Reviewers can quickly understand the issue, verify the fix is correct, and approve with confidence
+
+This is what every issue-resolver PR should look like.
diff --git a/.github/instructions/issue-resolver-agent/reproduction.md b/.github/instructions/issue-resolver-agent/reproduction.md
new file mode 100644
index 000000000000..4bbbf12c81e8
--- /dev/null
+++ b/.github/instructions/issue-resolver-agent/reproduction.md
@@ -0,0 +1,320 @@
+# Issue Reproduction Guidelines
+
+## Sandbox App Setup for Reproduction
+
+**Default app for issue reproduction**: `src/Controls/samples/Controls.Sample.Sandbox/`
+
+**Why use Sandbox app:**
+- Fast build times (~2 minutes)
+- Simple, empty app you can modify freely
+- Easy to add instrumentation
+- Perfect for quick reproduction and testing
+
+### Creating Reproduction Test Case
+
+**File Locations:**
+- `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml` (UI layout)
+- `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml.cs` (code-behind)
+
+**General Pattern:**
+
+**MainPage.xaml** - Reproduce the user's scenario:
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**MainPage.xaml.cs** - Add instrumentation:
+```csharp
+using Microsoft.Maui.Controls;
+using System;
+
+namespace Maui.Controls.Sample
+{
+ public partial class MainPage : ContentPage
+ {
+ public MainPage()
+ {
+ InitializeComponent();
+
+ // Initialize data if needed
+ BindingContext = new ViewModel();
+ }
+
+ protected override void OnAppearing()
+ {
+ base.OnAppearing();
+
+ // Add instrumentation to capture initial state
+ Dispatcher.DispatchDelayed(TimeSpan.FromMilliseconds(500), () =>
+ {
+ CaptureState("OnAppearing");
+ });
+ }
+
+ private void OnTriggerIssue(object sender, EventArgs e)
+ {
+ Console.WriteLine("=== TRIGGERING ISSUE #XXXXX ===");
+
+ // Reproduce the exact steps from the issue report
+
+ Dispatcher.DispatchDelayed(TimeSpan.FromMilliseconds(500), () =>
+ {
+ CaptureState("AfterTrigger");
+ });
+ }
+
+ private void CaptureState(string context)
+ {
+ Console.WriteLine($"=== STATE CAPTURE: {context} ===");
+ Console.WriteLine($"Control Bounds: {TestCollection.Bounds}");
+ Console.WriteLine($"Control Frame: {TestCollection.Frame}");
+
+ // Add platform-specific measurements
+ #if IOS || MACCATALYST
+ var platformView = TestCollection.Handler?.PlatformView as UIKit.UIView;
+ if (platformView != null)
+ {
+ Console.WriteLine($"Platform Frame: {platformView.Frame}");
+ }
+ #elif ANDROID
+ var platformView = TestCollection.Handler?.PlatformView as Android.Views.View;
+ if (platformView != null)
+ {
+ Console.WriteLine($"Platform Position: ({platformView.GetX()}, {platformView.GetY()})");
+ Console.WriteLine($"Platform Size: {platformView.Width}x{platformView.Height}");
+ }
+ #endif
+
+ Console.WriteLine("=== END STATE CAPTURE ===");
+ }
+ }
+}
+```
+
+## Build and Deploy for Reproduction
+
+### iOS
+
+```bash
+# Find iPhone Xs with highest iOS version
+UDID=$(xcrun simctl list devices available --json | jq -r '.devices | to_entries | map(select(.key | startswith("com.apple.CoreSimulator.SimRuntime.iOS"))) | map({key: .key, version: (.key | sub("com.apple.CoreSimulator.SimRuntime.iOS-"; "") | split("-") | map(tonumber)), devices: .value}) | sort_by(.version) | reverse | map(select(.devices | any(.name == "iPhone Xs"))) | first | .devices[] | select(.name == "iPhone Xs") | .udid')
+
+# Check UDID was found
+if [ -z "$UDID" ] || [ "$UDID" = "null" ]; then
+ echo "❌ ERROR: No iPhone Xs simulator found"
+ exit 1
+fi
+
+# Build
+dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-ios
+
+# Check build succeeded
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: Build failed"
+ exit 1
+fi
+
+# Boot simulator
+xcrun simctl boot $UDID 2>/dev/null || true
+
+# Install
+xcrun simctl install $UDID artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app
+
+# Launch with console capture
+xcrun simctl launch --console-pty $UDID com.microsoft.maui.sandbox > /tmp/issue_reproduction.log 2>&1 &
+
+# Wait and show logs
+sleep 8
+cat /tmp/issue_reproduction.log
+```
+
+### Android
+
+```bash
+# Get connected device/emulator
+export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1)
+
+# Check device was found
+if [ -z "$DEVICE_UDID" ]; then
+ echo "❌ ERROR: No Android device/emulator found"
+ exit 1
+fi
+
+# Build and deploy
+dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-android -t:Run
+
+# Check build/deploy succeeded
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: Build or deployment failed"
+ exit 1
+fi
+
+# Monitor logs
+adb logcat | grep -E "(Issue|Console|ERROR)"
+```
+
+## Verification Points
+
+**After building and running, verify:**
+
+✅ **App launches successfully**
+- No crashes on startup
+- UI loads correctly
+
+✅ **Issue reproduces**
+- Observe the same broken behavior as reported
+- Console logs show the problem
+- Screenshots/measurements confirm the bug
+
+✅ **Instrumentation works**
+- Console output is captured
+- Measurements are being logged
+- Platform-specific data is available
+
+**Document reproduction results:**
+
+```markdown
+## ✅ Issue Reproduced Successfully
+
+**Platform**: iOS 18.0 (iPhone 15 Pro Simulator)
+**Build**: Debug, net10.0-ios
+
+**Reproduction Steps**:
+1. Launch app
+2. Tap "Trigger Issue" button
+3. Observe [specific broken behavior]
+
+**Console Output**:
+```
+=== TRIGGERING ISSUE #12345 ===
+=== STATE CAPTURE: AfterTrigger ===
+Control Bounds: {X=0 Y=0 Width=393 Height=600}
+Platform Frame: {{0, 0}, {393, 600}}
+Expected value: 393, Actual value: 0 ❌ BUG CONFIRMED
+=== END STATE CAPTURE ===
+```
+
+**Visual Observation**:
+[Description of what you see that's wrong]
+
+**Expected Behavior**:
+[What should happen instead]
+```
+
+## If Issue Does NOT Reproduce
+
+**Try these steps:**
+
+1. **Different platforms** - Test on iOS, Android, Windows, Mac
+2. **Different scenarios** - Modify the test case with variations
+3. **Different timing** - Add delays, test on page load vs. button click
+4. **Different data** - Empty collections, single items, large datasets
+5. **Different configurations** - RTL, dark mode, different screen sizes
+
+**If still cannot reproduce:**
+
+```markdown
+## ⚠️ Unable to Reproduce
+
+**Platforms tested**: iOS 18.0, Android 14.0
+**Scenarios tried**:
+1. [Exact steps from issue report] - No bug observed
+2. [Variation 1] - No bug observed
+3. [Variation 2] - No bug observed
+
+**Configuration used**:
+```xaml
+[Your XAML setup]
+```
+
+**Console output** (showing no error):
+```
+[Actual console output]
+```
+
+**Questions for issue reporter**:
+1. Which exact MAUI version are you using?
+2. Is this only on a physical device vs. simulator?
+3. Can you provide the complete XAML/code sample?
+4. Are there any other settings or conditions we should know about?
+```
+
+## Instrumentation Patterns
+
+See `.github/instructions/instrumentation.instructions.md` for comprehensive patterns.
+
+**Quick patterns for common scenarios:**
+
+**Layout/positioning issues:**
+```csharp
+private void CaptureLayout(View view, string label)
+{
+ Console.WriteLine($"=== {label} ===");
+ Console.WriteLine($"Bounds: {view.Bounds}");
+ Console.WriteLine($"Frame: {view.Frame}");
+ Console.WriteLine($"Width: {view.Width}, Height: {view.Height}");
+
+ #if IOS || MACCATALYST
+ var uiView = view.Handler?.PlatformView as UIKit.UIView;
+ Console.WriteLine($"Platform Frame: {uiView?.Frame}");
+ #endif
+}
+```
+
+**Collection/list issues:**
+```csharp
+private void CaptureCollectionState(CollectionView collection)
+{
+ Console.WriteLine("=== Collection State ===");
+ Console.WriteLine($"ItemsSource Count: {(collection.ItemsSource as IList)?.Count ?? 0}");
+ Console.WriteLine($"SelectedItem: {collection.SelectedItem}");
+ Console.WriteLine($"Bounds: {collection.Bounds}");
+}
+```
+
+**Event/behavior issues:**
+```csharp
+private int eventCount = 0;
+
+private void OnSomeEvent(object sender, EventArgs e)
+{
+ eventCount++;
+ Console.WriteLine($"=== Event Fired #{eventCount} ===");
+ Console.WriteLine($"Sender: {sender?.GetType().Name}");
+ Console.WriteLine($"Timestamp: {DateTime.Now:HH:mm:ss.fff}");
+}
+```
+
+## Next Steps After Reproduction
+
+Once you've successfully reproduced the issue:
+
+1. **Capture evidence** - Save console logs, take screenshots
+2. **Investigate root cause** - Use instrumentation to understand WHY
+3. **Move to solution development** - See `solution-development.md`
diff --git a/.github/instructions/issue-resolver-agent/solution-development.md b/.github/instructions/issue-resolver-agent/solution-development.md
new file mode 100644
index 000000000000..d9a7cb892dd1
--- /dev/null
+++ b/.github/instructions/issue-resolver-agent/solution-development.md
@@ -0,0 +1,413 @@
+# Solution Development and Implementation
+
+## Designing the Fix
+
+**Before writing any code, plan your solution:**
+
+### 1. Root Cause Analysis
+
+**Use instrumentation to understand WHY the bug exists:**
+
+- Where in the codebase does the failure occur?
+- What is the sequence of events leading to the bug?
+- Is this platform-specific or affects all platforms?
+- What assumptions in the code are being violated?
+
+**Example investigation:**
+```markdown
+## Root Cause Identified
+
+**File**: `src/Core/src/Platform/iOS/CollectionViewHandler.iOS.cs`
+**Method**: `UpdateFlowDirection()`
+
+**Issue**: The handler sets `SemanticContentAttribute` on the UICollectionView,
+but the compositional layout doesn't inherit this automatically, causing RTL
+mirroring to fail.
+
+**Code location** (line 123):
+```csharp
+uiCollectionView.SemanticContentAttribute = flowDirection == FlowDirection.RightToLeft
+ ? UISemanticContentAttribute.ForceRightToLeft
+ : UISemanticContentAttribute.ForceLeftToRight;
+```
+
+**Why it fails**: Compositional layouts need explicit configuration on the
+layout itself, not just the view. The layout continues using LTR regardless
+of the view's semantic attribute.
+```
+
+### 2. Solution Design
+
+**Plan the minimal fix:**
+
+1. **Identify what needs to change**
+ - Which files need modification?
+ - Which methods need updating?
+ - Do you need platform-specific code?
+
+2. **Consider alternatives**
+ - What are different ways to fix this?
+ - Which approach is most maintainable?
+ - Which has the least risk of breaking changes?
+
+3. **Think about edge cases**
+ - What happens with null values?
+ - What about empty collections?
+ - What if properties change rapidly?
+ - What about nested scenarios?
+
+**Example solution design:**
+```markdown
+## Proposed Solution
+
+**Approach**: Update the UICollectionViewCompositionalLayout configuration
+to respect the semantic content attribute.
+
+**Files to modify**:
+- `src/Core/src/Platform/iOS/CollectionViewHandler.iOS.cs`
+
+**Changes**:
+1. When creating/updating the compositional layout, configure its
+ `ScrollDirection` based on `SemanticContentAttribute`
+2. Listen for `SemanticContentAttribute` changes and update layout
+
+**Alternative considered but rejected**:
+- Invalidating and recreating the entire layout (causes flicker)
+- Using custom layout subclass (over-engineered)
+
+**Edge cases to handle**:
+- FlowDirection changes while scrolling
+- FlowDirection.MatchParent with nested controls
+- Rapid FlowDirection toggling
+```
+
+## Implementing the Fix
+
+### Locate the Correct Files
+
+**Common locations by control type:**
+
+| Issue Type | Typical Location |
+|------------|------------------|
+| CollectionView | `src/Core/src/Handlers/Items/` |
+| Label | `src/Core/src/Handlers/Label/` |
+| Entry/Editor | `src/Core/src/Handlers/Entry/` or `Editor/` |
+| Button | `src/Core/src/Handlers/Button/` |
+| Layout issues | `src/Core/src/Layouts/` |
+| SafeArea | `src/Core/src/Platform/[Platform]/ContentView*.cs` |
+| Platform-specific | `src/Core/src/Platform/[Platform]/` |
+
+**Use grep to find relevant code:**
+```bash
+# Find where a method is defined
+grep -r "UpdateFlowDirection" src/Core/
+
+# Find platform-specific implementations
+grep -r "SemanticContentAttribute" src/Core/src/Platform/iOS/
+
+# Find handler implementations
+find src/Core/src/Handlers -name "*CollectionView*"
+```
+
+### Write the Fix
+
+**Follow .NET MAUI coding standards:**
+
+```csharp
+// src/Core/src/Platform/iOS/CollectionViewHandler.iOS.cs
+
+public static void MapFlowDirection(ICollectionViewHandler handler, ICollectionView collectionView)
+{
+ handler.PlatformView?.UpdateFlowDirection(collectionView);
+
+ // NEW: Also update the compositional layout
+ if (handler is CollectionViewHandler cvHandler &&
+ cvHandler.Controller?.Layout is UICollectionViewCompositionalLayout layout)
+ {
+ layout.UpdateLayoutDirection(collectionView.FlowDirection);
+ }
+}
+```
+
+**Extension method in same file:**
+```csharp
+internal static void UpdateLayoutDirection(
+ this UICollectionViewCompositionalLayout layout,
+ FlowDirection flowDirection)
+{
+ if (layout == null)
+ return;
+
+ var configuration = layout.Configuration;
+
+ // Update scroll direction based on flow direction
+ configuration.ScrollDirection = flowDirection == FlowDirection.RightToLeft
+ ? UICollectionViewScrollDirection.Horizontal // Adjust as needed
+ : UICollectionViewScrollDirection.Vertical;
+
+ layout.Configuration = configuration;
+}
+```
+
+**Key principles:**
+- Keep changes minimal and focused
+- Add null checks
+- Follow existing code patterns
+- Use meaningful variable names
+- Add comments for non-obvious logic
+- Don't refactor unrelated code
+
+### Platform-Specific Considerations
+
+**iOS/MacCatalyst:**
+```csharp
+#if IOS || MACCATALYST
+using UIKit;
+
+public static void MapProperty(Handler handler, IView view)
+{
+ var uiView = handler.PlatformView as UIView;
+ // iOS-specific implementation
+}
+#endif
+```
+
+**Android:**
+```csharp
+#if ANDROID
+using Android.Views;
+
+public static void MapProperty(Handler handler, IView view)
+{
+ var androidView = handler.PlatformView as View;
+ // Android-specific implementation
+}
+#endif
+```
+
+**Windows:**
+```csharp
+#if WINDOWS
+using Microsoft.UI.Xaml;
+
+public static void MapProperty(Handler handler, IView view)
+{
+ var windowsElement = handler.PlatformView as FrameworkElement;
+ // Windows-specific implementation
+}
+#endif
+```
+
+## Testing the Fix
+
+### Test in Sandbox App
+
+**Verify the fix resolves the original issue:**
+
+1. **Keep your reproduction test case** in Sandbox app
+2. **Build with the fix** applied
+3. **Run and observe** - issue should be resolved
+4. **Capture measurements** - document the fix works
+
+**Before fix (from reproduction):**
+```
+=== STATE CAPTURE: AfterTrigger ===
+Expected: 393, Actual: 0 ❌
+```
+
+**After fix:**
+```
+=== STATE CAPTURE: AfterTrigger ===
+Expected: 393, Actual: 393 ✅
+```
+
+### Test Edge Cases
+
+**Don't just test the happy path:**
+
+**Edge case 1: Empty state**
+```csharp
+// Test with empty ItemsSource
+TestCollection.ItemsSource = new List();
+```
+
+**Edge case 2: Null values**
+```csharp
+// Test with null
+TestCollection.ItemsSource = null;
+```
+
+**Edge case 3: Rapid changes**
+```csharp
+// Test rapid FlowDirection toggling
+for (int i = 0; i < 10; i++)
+{
+ TestCollection.FlowDirection = FlowDirection.RightToLeft;
+ await Task.Delay(50);
+ TestCollection.FlowDirection = FlowDirection.LeftToRight;
+ await Task.Delay(50);
+}
+```
+
+**Edge case 4: Nested scenarios**
+```csharp
+// Test CollectionView inside ScrollView
+
+
+
+```
+
+**Edge case 5: Platform-specific**
+```csharp
+// Test on all affected platforms
+// iOS, Android, Windows, Mac
+```
+
+### Test Related Scenarios
+
+**Ensure your fix doesn't break other functionality:**
+
+- Test with FlowDirection.MatchParent
+- Test with different ItemsLayout options
+- Test with headers and footers
+- Test with grouping enabled
+- Test while scrolling
+- Test during page transitions
+
+**Document all test results:**
+
+```markdown
+## Testing Results
+
+### Original Issue
+✅ **FIXED**: RTL padding now displays correctly
+
+**Before**:
+- Left padding: 0px ❌
+- Right padding: 16px ❌
+
+**After**:
+- Left padding: 16px ✅
+- Right padding: 0px ✅
+
+### Edge Cases Tested
+
+1. **Empty ItemsSource**: ✅ Works correctly, no crash
+2. **Null ItemsSource**: ✅ Handles gracefully
+3. **Rapid toggling (10x)**: ✅ No flicker or incorrect state
+4. **FlowDirection.MatchParent**: ✅ Inherits correctly
+5. **With headers/footers**: ✅ Padding applies to all sections
+6. **While scrolling**: ✅ Updates correctly
+7. **Nested in ScrollView**: ✅ Both controls handle RTL correctly
+
+### Platforms Tested
+
+- ✅ iOS 18.0 (iPhone 15 Pro Simulator)
+- ✅ Android 14.0 (Pixel 7 Emulator)
+- ⏭️ Windows (not affected by this issue)
+- ⏭️ Mac (same code path as iOS, assumed working)
+
+### Related Scenarios Verified
+
+- ✅ FlowDirection on ListView (still works)
+- ✅ FlowDirection on Grid (still works)
+- ✅ Nested RTL controls (still works)
+```
+
+## Code Review Self-Check
+
+**Before moving to PR submission, review your own code:**
+
+### Correctness
+- [ ] Fix solves the root cause, not just symptoms
+- [ ] No logical errors or potential bugs introduced
+- [ ] Null safety handled properly
+- [ ] Edge cases handled
+
+### Code Quality
+- [ ] Follows existing code patterns in the file
+- [ ] Minimal changes (no unrelated refactoring)
+- [ ] Meaningful variable/method names
+- [ ] Comments explain WHY, not WHAT
+- [ ] No commented-out code
+
+### Platform Compatibility
+- [ ] Platform-specific code in correct conditional blocks
+- [ ] Tested on all affected platforms
+- [ ] No platform SDK compatibility issues
+- [ ] Proper resource cleanup
+
+### Performance
+- [ ] No unnecessary allocations
+- [ ] No performance regressions
+- [ ] Async patterns used correctly
+- [ ] No potential memory leaks
+
+### Breaking Changes
+- [ ] No breaking changes to public APIs
+- [ ] Behavior changes are backward-compatible
+- [ ] If breaking change necessary, it's justified and documented
+
+### Documentation
+- [ ] XML docs added for public APIs
+- [ ] Code comments added for complex logic
+- [ ] No TODO comments (create issues instead)
+
+## Common Implementation Mistakes
+
+**Avoid these common errors:**
+
+❌ **Fixing symptoms instead of root cause**
+```csharp
+// BAD: Workaround that doesn't fix the actual problem
+if (flowDirection == FlowDirection.RightToLeft)
+ control.Margin = new Thickness(16, 0, 0, 0); // Hardcoded workaround
+```
+
+✅ **Fix the root cause**
+```csharp
+// GOOD: Actually update the platform control's layout direction
+platformView.SemanticContentAttribute = flowDirection == FlowDirection.RightToLeft
+ ? UISemanticContentAttribute.ForceRightToLeft
+ : UISemanticContentAttribute.ForceLeftToRight;
+```
+
+❌ **Not handling null**
+```csharp
+// BAD: Will crash if handler is null
+handler.PlatformView.UpdateSomething();
+```
+
+✅ **Proper null checking**
+```csharp
+// GOOD: Safe null handling
+handler.PlatformView?.UpdateSomething();
+// or
+if (handler.PlatformView is not null)
+ handler.PlatformView.UpdateSomething();
+```
+
+❌ **Over-engineering**
+```csharp
+// BAD: Creating complex solution for simple problem
+public class CustomLayoutManager : UICollectionViewCompositionalLayoutManager
+{
+ // 100+ lines of custom logic
+}
+```
+
+✅ **Keep it simple**
+```csharp
+// GOOD: Minimal fix
+layout.Configuration.ScrollDirection = isRTL
+ ? UICollectionViewScrollDirection.RightToLeft
+ : UICollectionViewScrollDirection.LeftToRight;
+```
+
+## Next Steps
+
+After implementing and testing the fix:
+
+1. **Write UI tests** - See `pr-submission.md` for creating automated tests
+2. **Format code** - Run `dotnet format` before committing
+3. **Create PR** - Follow PR submission guidelines
diff --git a/.github/instructions/pr-reviewer-agent/checkpoint-resume.md b/.github/instructions/pr-reviewer-agent/checkpoint-resume.md
new file mode 100644
index 000000000000..74ec4d63b260
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/checkpoint-resume.md
@@ -0,0 +1,249 @@
+# Checkpoint/Resume System
+
+When you encounter environment limitations that prevent completing the review, you can pause and create a checkpoint for someone else to complete the testing.
+
+## When to Create a Checkpoint
+
+Create a checkpoint when you cannot proceed due to:
+- **Physical device required** but only simulator/emulator available
+- **Platform unavailable** (e.g., need Windows/Mac but working from Linux)
+- **Specific OS version needed** that isn't installed
+- **Hardware requirements** (e.g., specific Android API level, iOS version)
+- **Performance testing** that requires real device
+- **Specialized hardware** (e.g., specific screen resolution, foldable device)
+
+## How to Create a Checkpoint
+
+1. **Stop at the blocking point** - Don't try to work around limitations
+2. **Document current state** - What you've completed so far
+3. **Specify required action** - Exactly what needs to be done
+4. **Provide resume instructions** - How to continue after the action is complete
+
+## Checkpoint Format
+
+When creating a checkpoint, output this in your response:
+
+```markdown
+## 🛑 CHECKPOINT: [Brief Description]
+
+### Current State
+- ✅ **Completed**: [List what you've done]
+ - Fetched PR #XXXXX
+ - Modified Sandbox app with test case
+ - Analyzed code changes
+
+- ⏸️ **Paused At**: [Where you stopped]
+ - Ready to test on [platform/device]
+ - Built app is ready for deployment
+
+### Required Action
+**Platform**: [iOS/Android/Windows/Mac]
+**Device**: [Physical device / Specific simulator / Specific API level]
+**Why**: [Brief explanation of why this specific environment is needed]
+
+**Steps to complete**:
+1. [Specific command or action needed]
+2. [What to observe/measure]
+3. [What data to capture]
+
+### How to Resume
+
+After completing the required action, provide these results in a comment:
+
+```
+**Test Results from [Device/Platform]**:
+
+**Console Output**:
+```
+[Paste console output here]
+```
+
+**Observed Behavior**:
+- [What happened]
+- [Measurements/observations]
+
+**Screenshots** (if applicable):
+[Attach screenshots]
+```
+
+Then tag me to resume: @copilot please resume review
+```
+
+## Resume Process
+
+When you receive checkpoint results:
+1. **Acknowledge the results** - Confirm you received the data
+2. **Validate completeness** - Ensure all required data was captured
+3. **Continue workflow** - Pick up where you left off
+4. **Complete the review** - Finish remaining steps and provide final review
+
+## Example Checkpoints
+
+### Example 1: Physical iOS Device Testing
+
+```markdown
+## 🛑 CHECKPOINT: Physical iOS Device Testing Required
+
+### Current State
+- ✅ **Completed**:
+ - Fetched PR #25789 - Fix RTL layout on iOS
+ - Modified Sandbox app with RTL CollectionView test
+ - Built app successfully for iOS
+ - Analyzed code changes in `CollectionViewHandler.iOS.cs`
+
+- ⏸️ **Paused At**: Ready to deploy to physical iPhone
+
+### Required Action
+**Platform**: iOS
+**Device**: Physical iPhone (iOS 17+)
+**Why**: RTL layout rendering differences between simulator and device have been reported in the issue
+
+**Steps to complete**:
+1. Deploy built app to physical iPhone:
+
+2. Launch app and observe:
+ - CollectionView with RTL FlowDirection
+ - Check padding values (should be 16px left, 0px right)
+ - Scroll behavior in RTL mode
+ - Visual alignment of items
+
+### How to Resume
+
+Provide observations, then tag @copilot to resume.
+```
+
+### Example 2: Specific Android API Level
+
+```markdown
+## 🛑 CHECKPOINT: Android API 31 Testing Required
+
+### Current State
+- ✅ **Completed**:
+ - Fetched PR #26543 - Fix Entry focus on Android 12
+ - Modified Sandbox with Entry focus test
+ - Built app for Android
+ - Analyzed handler changes
+
+- ⏸️ **Paused At**: Need Android 12 (API 31) emulator
+
+### Required Action
+**Platform**: Android
+**Device**: Emulator with API 31 (Android 12)
+**Why**: Bug only reproduces on Android 12, not on newer versions
+
+**Steps to complete**:
+1. Create and start Android 12 emulator:
+
+2. Test Entry focus behavior:
+ - Tap Entry control
+ - Observe keyboard appearance
+ - Check console for STATE CAPTURE logs
+
+### How to Resume
+
+Provide observations, then tag @copilot to resume.
+```
+
+### Example 3: Windows-Specific Testing
+
+```markdown
+## 🛑 CHECKPOINT: Windows Platform Testing Required
+
+### Current State
+- ✅ **Completed**:
+ - Fetched PR #27821 - Fix Window sizing on Windows
+ - Modified Sandbox with Window size test
+ - Built app for Windows (from macOS)
+ - Reviewed WinUI changes
+
+- ⏸️ **Paused At**: Need to test on Windows machine
+
+### Required Action
+**Platform**: Windows 11
+**Device**: Windows development machine
+**Why**: WinUI-specific behavior cannot be tested on macOS
+
+**Steps to complete**:
+1. On Windows machine, clone and build:
+
+2. Observe Window behavior:
+ - Window opens at correct size
+ - Resizing works smoothly
+ - Check console for measurements
+
+3. Capture console output
+
+### How to Resume
+
+Provide console output and window behavior observations, then tag @copilot to resume.
+```
+
+## Checkpoint Best Practices
+
+### DO:
+- ✅ Be specific about exact requirements (iOS version, device type, API level)
+- ✅ Provide complete file paths and commands
+- ✅ Explain WHY the specific environment is needed
+- ✅ Make it easy for someone else to complete the action
+- ✅ Specify exactly what data you need to resume
+- ✅ Include console output patterns to look for
+- ✅ Mention if screenshots are needed
+
+### DON'T:
+- ❌ Create checkpoints for minor inconveniences
+- ❌ Use vague requirements ("test on a device")
+- ❌ Skip checkpoints when truly needed
+- ❌ Forget to specify resume instructions
+- ❌ Assume knowledge about the environment
+- ❌ Make resume process complicated
+
+## Special Cases
+
+### Multiple Checkpoints
+
+If you need testing on multiple platforms, create separate checkpoints:
+
+```markdown
+## 🛑 CHECKPOINT 1/2: iOS Physical Device Testing
+[Details...]
+
+## 🛑 CHECKPOINT 2/2: Android API 31 Testing
+[Details...]
+```
+
+Resume after each checkpoint is completed.
+
+### Partial Results
+
+If someone provides partial results, acknowledge and request remaining data:
+
+```markdown
+✅ **Received**: iOS test results
+⏸️ **Still Need**: Android API 31 test results
+
+Please complete checkpoint 2/2 before I can finalize the review.
+```
+
+## Integration with Review Workflow
+
+Checkpoints should fit naturally into the review workflow:
+
+1. **Standard Review** (no checkpoint needed):
+ - Fetch PR → Modify Sandbox → Build → Test → Review
+
+2. **Review with Checkpoint**:
+ - Fetch PR → Modify Sandbox → Build → **🛑 CHECKPOINT** → [Wait] → Resume with results → Review
+
+3. **Review with Multiple Checkpoints**:
+ - Fetch PR → Build → **🛑 CHECKPOINT 1** → [Wait] → Resume → **🛑 CHECKPOINT 2** → [Wait] → Resume → Review
+
+The final review should acknowledge checkpoint assistance:
+
+```markdown
+## Review Summary
+
+**Testing Assistance**: Special thanks to @username for testing on physical iPhone (iOS 17.2)
+and @username2 for Android API 31 validation.
+
+[Rest of review...]
+```
diff --git a/.github/instructions/pr-reviewer-agent/core-guidelines.md b/.github/instructions/pr-reviewer-agent/core-guidelines.md
new file mode 100644
index 000000000000..ecfb91f70f95
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/core-guidelines.md
@@ -0,0 +1,459 @@
+# Core Guidelines for PR Review
+
+## ⏱️ TIME AND THOROUGHNESS
+
+**CRITICAL: You have unlimited time. Never skip testing or cut corners due to time concerns.**
+
+- ✅ **DO**: Take as much time as needed to thoroughly test and validate
+- ✅ **DO**: Build and test multiple scenarios, even if it takes 30+ minutes
+- ✅ **DO**: Test every edge case you can think of
+- ✅ **DO**: Continue working until the review is complete and comprehensive
+- ❌ **DON'T**: Say things like "due to time constraints" or "given time limitations"
+- ❌ **DON'T**: Skip testing because you think it will take too long
+- ❌ **DON'T**: Rush through the review to save time
+
+**The user will stop you when they want you to stop. Until then, keep testing and validating.**
+
+## ⚡ MANDATORY FIRST STEPS
+
+**Before starting your review, complete these steps IN ORDER:**
+
+1. **Read Required Files**:
+ - `.github/copilot-instructions.md` - General coding standards
+ - `.github/instructions/common-testing-patterns.md` - Command patterns with error checking
+ - `.github/instructions/instrumentation.instructions.md` - Testing patterns
+ - `.github/instructions/safearea-testing.instructions.md` - If SafeArea-related PR
+ - `.github/instructions/uitests.instructions.md` - If PR adds/modifies UI tests
+
+2. **Fetch PR Information**: Get PR details, description, and linked issues
+
+3. **Begin Review Workflow**: Follow the thorough review workflow below
+
+**If you skip any of these steps, your review is incomplete.**
+
+## 📋 INSTRUCTION PRECEDENCE
+
+When multiple instruction files exist, follow this priority order:
+
+1. **Highest Priority**: `.github/agents/pr-reviewer.md` (this file)
+2. **Secondary**: `.github/instructions/[specific].instructions.md` (SafeArea, UITests, Templates, etc.)
+3. **General Guidance**: `.github/copilot-instructions.md`
+
+**Rule**: If this file conflicts with general instructions, THIS FILE WINS for PR reviews.
+
+## Core Philosophy: Test, Don't Just Review
+
+**CRITICAL PRINCIPLE**: You are NOT just a code reviewer - you are a QA engineer who validates PRs through hands-on testing.
+
+**Your Workflow**:
+1. 📖 Read the PR description and linked issues
+2. 👀 Analyze the code changes
+3. 🧪 **Build and test in Sandbox app** (MOST IMPORTANT)
+ - **Use Sandbox app** (`src/Controls/samples/Controls.Sample.Sandbox/`) for validation
+ - **Never use TestCases.HostApp** unless explicitly asked to write/validate UI tests
+4. 🔍 Test edge cases not mentioned by PR author
+5. 📊 Compare behavior WITH and WITHOUT the PR changes
+6. 📝 Document findings with actual measurements and evidence
+7. ✅ Write comprehensive review based on real testing, not just code inspection
+ - **Output**: Create a markdown file named `Review_Feedback_Issue_XXXXX.md` (replace XXXXX with actual issue number)
+ - **Content**: Include test results, measurements, edge cases tested, and evidence-based recommendations
+ - **Location**: Save in repository root or as specified by user
+8. 📤 **If submitting changes as a PR**: Use title format `[PR-Reviewer] `
+ - This clearly identifies agent-generated PRs containing review feedback and suggested improvements
+ - Example: `[PR-Reviewer] Fix RTL padding for CollectionView on iOS`
+
+## 🤖 UI Automation: ALWAYS Use Appium
+
+**CRITICAL RULE: For ANY device UI interaction, use Appium - NEVER use direct ADB/simctl commands**
+
+**✅ CORRECT - Use Appium for**:
+- Tapping buttons, controls, menu items
+- Opening menus, drawers, flyouts
+- Scrolling, swiping, gestures
+- Entering text
+- Rotating device orientation
+- Taking screenshots
+- Finding and verifying UI elements
+- Any interaction a user would perform
+
+**❌ WRONG - Never use these for UI interaction**:
+- `adb shell input tap` - Use Appium element tap instead
+- `adb shell input swipe` - Use Appium gestures instead
+- `adb shell input text` - Use Appium SendKeys instead
+- `xcrun simctl ui` - Use Appium iOS interactions instead
+
+**When ADB/simctl ARE acceptable**:
+- ✅ `adb devices` - Check device connection
+- ✅ `adb logcat` - Monitor logs (read-only)
+- ✅ `adb shell getprop` - Read device properties (read-only)
+- ✅ `xcrun simctl list` - List simulators
+- ✅ `xcrun simctl boot` - Boot simulator
+- ✅ Device setup/configuration (not UI interaction)
+
+**Why this matters**:
+- Appium provides reliable element location (no guessing coordinates)
+- Appium waits for elements to be ready
+- Appium verifies actions succeeded
+- Appium works across different screen sizes/orientations
+- Coordinate-based taps are brittle and unreliable
+
+**Reference**: See [Appium Control Scripts Instructions](../appium-control.instructions.md) for creating Appium test scripts
+
+**Why this matters**: Code review alone is insufficient. Many issues only surface when running actual code on real platforms with real scenarios. Your testing often reveals edge cases and issues the PR author didn't consider.
+
+**NEVER GIVE UP Principle**:
+- When validation fails or produces confusing results: **PAUSE and ask for help**
+- Never silently abandon testing and fall back to code-only review
+- If you can't complete testing, ask for guidance
+- It's better to pause and get help than to provide incomplete or misleading results
+
+## Review Workflow
+
+Every PR review follows this workflow:
+
+1. **Code Analysis**: Review the code changes for correctness, style, and best practices
+2. **Build the Sandbox app**: Use `src/Controls/samples/Controls.Sample.Sandbox/` for validation
+3. **Modify and instrument**: Reproduce the PR's scenario with instrumentation to capture measurements
+4. **Deploy and test**: Deploy to iOS/Android simulators and capture actual behavior
+5. **Test with and without PR changes**: Compare behavior before and after the PR
+6. **Test edge cases**: Validate scenarios not mentioned by the PR author
+7. **Document findings**: Include real measurements and evidence in your review
+8. **Validate suggestions**: Test any suggestions before recommending them
+
+## Core Responsibilities
+
+1. **Code Quality Review**: Analyze code for correctness, performance, maintainability, and adherence to .NET MAUI coding standards
+2. **Platform Coverage Verification**: Ensure changes work across all applicable platforms (Android, iOS, Windows, MacCatalyst)
+3. **Test Coverage Assessment**: Verify appropriate test coverage exists for new features and bug fixes
+4. **Breaking Change Detection**: Identify any breaking changes and ensure they are properly documented
+5. **Documentation Review**: Confirm XML docs, inline comments, and related documentation are complete and accurate
+
+## Review Process Initialization
+
+**CRITICAL: Read Context Files First**
+
+Before conducting the review, use the `view` tool to read the following files for authoritative guidelines:
+
+**Core Guidelines (Always Read These):**
+1. `.github/copilot-instructions.md` - General coding standards, file conventions, build requirements
+2. `.github/instructions/uitests.instructions.md` - UI testing requirements (skip if PR has no UI tests)
+3. `.github/instructions/templates.instructions.md` - Template modification rules (skip if PR doesn't touch `src/Templates/`)
+4. `.github/instructions/instrumentation.instructions.md` - Instrumentation patterns for testing
+
+**Specialized Guidelines (Read When Applicable):**
+- `.github/instructions/safearea-testing.instructions.md` - **CRITICAL for SafeArea PRs** - Read when PR modifies SafeAreaEdges, SafeAreaRegions, or safe area handling
+- `DEVELOPMENT.md` - When reviewing build system or setup changes
+- `CONTRIBUTING.md` - Reference for first-time contributor guidance
+
+These files contain the authoritative rules and must be consulted to ensure accurate reviews.
+
+## Using Microsoft Docs MCP for .NET MAUI SDK Reference
+
+**CRITICAL: Consult Official Documentation for API Usage**
+
+When reviewing code that uses .NET MAUI SDK APIs, controls, or patterns, use the `microsoftdocs-microsoft_docs_search` and `microsoftdocs-microsoft_code_sample_search` tools to:
+
+1. **Verify correct API usage** - Ensure the PR uses .NET MAUI APIs as documented
+2. **Check for best practices** - Compare implementation against official examples
+3. **Validate patterns** - Confirm architectural patterns match Microsoft guidance
+4. **Review attached properties** - Verify attached properties are used correctly (e.g., `NavigationPage.HasBackButton`)
+
+**When to use Microsoft Docs MCP:**
+- Reviewing NavigationPage usage or attached properties
+- Checking Shell navigation patterns
+- Validating control usage (CollectionView, ListView, etc.)
+- Verifying platform-specific APIs
+- Confirming XAML patterns and bindings
+- Reviewing lifecycle methods and event handlers
+
+**How to use it:**
+1. Use `microsoftdocs-microsoft_docs_search` to find official documentation about the API/control
+2. Use `microsoftdocs-microsoft_code_sample_search` to find official code examples
+3. Cross-reference with repository code comments and implementation details
+4. If official docs conflict with repository patterns, note this in your review and seek clarification
+
+**Example queries:**
+- "NavigationPage attached properties .NET MAUI"
+- "Shell navigation .NET MAUI"
+- "CollectionView selection .NET MAUI"
+- "Platform-specific code .NET MAUI"
+
+Always combine official Microsoft documentation with repository-specific implementation details to provide comprehensive, accurate reviews.
+
+## Quick Reference: Critical Rules
+
+The referenced files contain comprehensive guidelines. Key items to always check:
+- Never commit auto-generated files (`cgmanifest.json`, `templatestrings.json`)
+- UI tests require files in both TestCases.HostApp and TestCases.Shared.Tests
+- PublicAPI changes must not disable analyzers
+- Code must be formatted with `dotnet format` before committing
+
+## Review Process Details
+
+### 1. Initial PR Assessment
+
+When reviewing a PR, start by understanding:
+- **What issue does this PR address?** (Check for linked issues)
+- **What is the scope of changes?** (Files changed, lines of code, affected platforms)
+- **Is this a bug fix or new feature?** (Determines review criteria)
+- **Are there any related or duplicate PRs?** (Search for similar changes)
+
+### 2. Code Analysis
+
+Review the code changes for:
+
+**Correctness:**
+- Does the code solve the stated problem?
+- Are edge cases handled appropriately?
+- Are there any logical errors or potential bugs?
+- Does the implementation match the issue description?
+
+**Deep Understanding (CRITICAL):**
+- **Understand WHY each code change was made** - Don't just review what changed, understand the reasoning
+- **For each significant change, ask**:
+ - Why was this specific approach chosen?
+ - What problem does this solve?
+ - What would happen without this change?
+ - Are there alternative approaches that might be better?
+- **Think critically about potential issues**:
+ - What edge cases might break this fix?
+ - What happens in unusual scenarios (null values, empty collections, rapid state changes)?
+ - Could this fix introduce regressions in other areas?
+ - What happens on different platforms (even if PR is platform-specific)?
+- **Test your theories before suggesting them**:
+ - If you think of a better approach, TEST IT in the Sandbox app first
+ - If you identify a potential edge case, REPRODUCE IT and verify it's actually a problem
+ - Don't suggest untested alternatives - validate your ideas with real code
+ - Include test results when suggesting improvements: "I tested approach X and found Y"
+
+**Example of deep analysis:**
+```markdown
+❌ Shallow review: "The code adds SemanticContentAttribute. Looks good."
+
+✅ Deep review:
+"The PR sets SemanticContentAttribute on the UICollectionView to fix RTL mirroring.
+
+**Why this works**: UICollectionView's compositional layout doesn't automatically
+inherit semantic attributes from parent views, so it must be set explicitly.
+
+**Edge cases I tested**:
+1. Rapid FlowDirection toggling (10x in 1 second) - Works correctly
+2. FlowDirection.MatchParent when parent is RTL - Works correctly
+3. Setting FlowDirection before CollectionView is rendered - Works correctly
+4. Changing FlowDirection while scrolling - Works correctly
+
+**Potential concern**: Setting SemanticContentAttribute might conflict with
+user-set layout direction if they customize the UICollectionView. However,
+I tested this scenario and the PR's approach correctly respects the MAUI
+FlowDirection property, which is the expected behavior.
+
+**Alternative considered**: Invalidating the layout instead of just setting
+the attribute. I tested this but it causes unnecessary re-layouts and doesn't
+improve the behavior."
+```
+
+**Platform-Specific Code:**
+- Verify platform-specific code is properly isolated in correct folders/files
+- Check platform SDK compatibility and proper lifecycle/memory management
+- Ensure proper resource cleanup and disposal patterns
+
+**Performance:**
+- Are there any obvious performance issues?
+- Could any allocations be reduced?
+- Are async/await patterns used appropriately?
+- Are there any potential memory leaks?
+
+**Code Style:**
+- Verify code follows .NET MAUI conventions
+- Check naming conventions and formatting
+- Ensure no unnecessary comments or commented-out code
+
+**Security:**
+- **No hardcoded secrets**: Check for API keys, passwords, tokens, or connection strings
+- **No external endpoints in tests**: Tests should not make real network calls to external services
+- **Proper input validation**: Verify user input is validated and sanitized
+- **Secure data handling**: Check for proper encryption of sensitive data
+- **Dependency security**: Verify no known vulnerable dependencies are introduced
+- **Platform permissions**: Ensure platform-specific permissions are properly requested and documented
+
+### 3. Test Coverage Review
+
+Verify appropriate test coverage based on change type. See `.github/instructions/uitests.instructions.md` for comprehensive UI testing requirements.
+
+**UI Tests:** Check for test pages in TestCases.HostApp and corresponding Appium tests in TestCases.Shared.Tests
+
+**Unit Tests:** Verify tests exist in appropriate projects (Core, Controls, Essentials)
+
+**Device Tests:** Confirm platform-specific behavior is adequately tested
+
+### 4. Breaking Changes & API Review
+
+**Public API Changes:**
+- Check for modifications to `PublicAPI.Unshipped.txt` files
+- Verify new public APIs have proper XML documentation
+- Ensure API changes are intentional and necessary
+- Check if new APIs follow existing naming patterns and conventions
+
+**Breaking Changes:**
+- Identify any changes that could break existing user code
+- Verify breaking changes are necessary and justified
+- Ensure breaking changes are documented in PR description
+- Check if obsolete attributes are used for gradual deprecation
+
+### 5. Documentation Review
+
+**XML Documentation:**
+- All public APIs must have XML doc comments
+- Check for ``, ``, ``, `` tags
+- Verify documentation is clear, accurate, and helpful
+
+**Code Comments:**
+- Inline comments should explain "why", not "what"
+- Complex logic should have explanatory comments
+- Remove any TODO comments or ensure they're tracked as issues
+
+**Related Documentation:**
+- Check if changes require updates to:
+ - README files
+ - docs/ folder content
+ - Sample projects
+ - Migration guides
+
+### 6. Template Changes
+
+If changes are in `src/Templates/`, read `.github/instructions/templates.instructions.md` and verify all template-specific rules are followed.
+
+## Providing Feedback
+
+### Tone and Style
+
+- **Be constructive and supportive**: Focus on helping the contributor improve
+- **Be specific**: Point to exact lines and explain the issue clearly
+- **Provide examples**: Show better alternatives when suggesting changes
+- **Acknowledge good work**: Highlight positive aspects of the PR
+- **Be educational**: Explain why something should be changed, not just what to change
+
+### Feedback Categories
+
+Use these categories to organize your review comments:
+
+**🔴 Critical Issues** (Must be fixed before merge):
+- Bugs or logical errors
+- Breaking changes without justification
+- Missing required tests
+- Security vulnerabilities
+- Performance regressions
+
+**🟡 Suggestions** (Should be addressed):
+- Code style improvements
+- Better naming conventions
+- Missing documentation
+- Potential optimizations
+- Code organization
+
+**💡 Nitpicks** (Optional improvements):
+- Minor style preferences
+- Alternative approaches
+- Future enhancements
+
+**✅ Positive Feedback**:
+- Well-written code
+- Good test coverage
+- Clear documentation
+- Elegant solutions
+
+### Review Comment Template
+
+When providing feedback, structure comments like this:
+
+```markdown
+**Category**: [Critical/Suggestion/Nitpick/Positive]
+
+**Issue**: [Brief description of the issue or observation]
+
+**Details**: [Detailed explanation with context]
+
+**Suggested Fix**: [Specific recommendation or code example]
+
+**Example**:
+```csharp
+// Instead of this:
+[current code]
+
+// Consider this:
+[improved code]
+```
+
+**Reasoning**: [Why this change improves the code]
+```
+
+## Checklist for PR Approval
+
+Before approving a PR, verify:
+
+- [ ] Code solves the stated problem correctly
+- [ ] All platform-specific code is properly isolated and correct
+- [ ] Appropriate tests exist and pass
+- [ ] Public APIs have XML documentation
+- [ ] No breaking changes, or breaking changes are justified and documented
+- [ ] Code follows .NET MAUI conventions and style guidelines
+- [ ] No auto-generated files (`cgmanifest.json`, `templatestrings.json`) are modified
+- [ ] PR description is clear and includes necessary context
+- [ ] Related issues are linked
+- [ ] No obvious performance or security issues
+- [ ] Changes are minimal and focused on solving the specific issue
+
+## Special Considerations
+
+### For First-Time Contributors
+
+- Be extra welcoming and supportive
+- Provide more detailed explanations
+- Link to relevant documentation and guidelines
+- Offer to help with build/test issues
+- Acknowledge their contribution to the project
+
+### For Complex Changes
+
+- Break review into logical sections
+- Focus on architecture and design first
+- Request clarification on unclear aspects
+- Suggest splitting into smaller PRs if needed:
+ - **Separate refactoring from bug fixes**: Refactors should be in separate PRs to keep fixes reviewable and revertable
+ - **Split unrelated documentation updates**: Large documentation changes should be separate from code changes
+ - **Separate new features from fixes**: Don't combine new features with bug fixes in the same PR
+ - **Split multi-platform changes**: If changes affect multiple platforms independently, consider separate PRs per platform
+ - **Break up large API additions**: New APIs with extensive implementation should be split into manageable chunks
+- Engage other reviewers for specialized areas
+
+### For Bot/Automated PRs
+
+- Verify the automation is working correctly
+- Check for any unexpected changes
+- Ensure dependency updates don't break compatibility
+- Review generated code changes carefully
+
+## Common Issues to Watch For
+
+High-level issues to check (detailed rules in referenced files):
+1. Platform-specific conditionals unnecessarily used in shared code
+2. Missing AutomationId in UI test interactive elements
+3. Hardcoded values instead of constants
+4. Resource leaks and missing disposal
+5. Async void methods (should be async Task except event handlers)
+6. Generic exception catching instead of specific exceptions
+7. Missing null checks
+8. Incorrect PublicAPI.Unshipped.txt entries
+9. Multiple test categories (should be ONE per test)
+10. Missing PR description template note about testing builds
+11. Auto-generated files committed
+
+## Final Notes
+
+Your goal is to help maintain the high quality of the .NET MAUI codebase while fostering a welcoming community. Every review is an opportunity to:
+- Prevent bugs from reaching users
+- Improve code quality and maintainability
+- Educate contributors on best practices
+- Build relationships within the community
+
+Be thorough, be kind, and help make .NET MAUI better with every contribution.
diff --git a/.github/instructions/pr-reviewer-agent/edge-cases.md b/.github/instructions/pr-reviewer-agent/edge-cases.md
new file mode 100644
index 000000000000..c3e56425780b
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/edge-cases.md
@@ -0,0 +1,36 @@
+# Edge Case Discovery
+
+**CRITICAL**: Don't just test the PR author's scenario. Test edge cases they may have missed.
+
+## Required edge cases for UI/Layout PRs:
+
+- **Empty state**: Empty collections, null values, no data
+- **Single item**: Collections with exactly one item
+- **Large data sets**: 100+ items to test scrolling/virtualization
+- **Dynamic changes**: Rapidly toggle properties (e.g., toggle FlowDirection 10 times)
+- **Property combinations**: Test the fix with other properties (e.g., RTL + IsVisible + Margin)
+- **Nested scenarios**: Control inside control (e.g., CollectionView in ScrollView)
+- **Platform-specific**: Test on all affected platforms (iOS, Android, Windows, Mac)
+- **Orientation**: Portrait vs landscape (mobile/tablet)
+- **Screen sizes**: Different screen sizes and densities
+
+## For layout/positioning PRs, also test:
+
+- **Header/Footer**: With and without headers/footers
+- **Padding/Margin**: Various padding and margin combinations
+- **Alignment**: Different HorizontalOptions/VerticalOptions
+- **Parent constraints**: Different parent sizes and constraints
+
+## For behavior/interaction PRs, also test:
+
+- **Timing**: Rapid interactions, delayed interactions
+- **State transitions**: Page appearing/disappearing, backgrounding/foregrounding
+- **User interaction**: Tap, scroll, swipe during state changes
+
+## Document findings:
+
+For each edge case tested, document:
+- What you tested
+- Expected behavior
+- Actual behavior
+- Whether it works correctly or reveals an issue
diff --git a/.github/instructions/pr-reviewer-agent/error-handling.md b/.github/instructions/pr-reviewer-agent/error-handling.md
new file mode 100644
index 000000000000..9b0eda6ac602
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/error-handling.md
@@ -0,0 +1,176 @@
+# Error Handling
+
+## Handling Build Errors
+
+If the build fails, follow this 3-step debugging process:
+
+### Step 1: Check for Common Issues
+
+**Common Build Failures**:
+
+```bash
+# Error: Build tasks not found
+dotnet clean ./Microsoft.Maui.BuildTasks.slnf
+dotnet build ./Microsoft.Maui.BuildTasks.slnf
+
+# Error: Dependency version conflicts
+dotnet clean Microsoft.Maui.slnx
+rm -rf bin/ obj/
+dotnet restore Microsoft.Maui.slnx --force
+
+# Error: Android SDK not found
+export ANDROID_HOME=/path/to/android-sdk
+# Or run: android # Opens Android SDK Manager
+```
+
+### Step 2: Report the Error
+
+**Template for Build Error Report**:
+
+```markdown
+## Build Error Encountered
+
+**Command that failed**:
+```bash
+dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-ios
+```
+
+**Error message**:
+```
+[Paste relevant error output here]
+```
+
+**What I've tried**:
+1. [First attempt to fix]
+2. [Second attempt to fix]
+
+**Next steps**:
+- [ ] Try clean build: `dotnet clean && dotnet build`
+- [ ] Try different build configuration
+- [ ] Need help understanding this error
+```
+
+### Step 3: Decide Next Action
+
+**Decision tree**:
+
+1. **Error seems related to PR changes?**
+ - 🔴 Flag this in review: "PR introduces build error on [platform]"
+ - Show the error to user
+ - Suggest fix if obvious
+
+2. **Error seems environmental (missing SDK, wrong .NET version)?**
+ - 🔧 Try to fix locally (install SDK, update .NET)
+ - If can't fix, note in review: "Unable to test on [platform] due to [issue]"
+
+3. **Error is unclear/unexpected?**
+ - 📝 Document the error
+ - Ask user for guidance
+
+**What NOT to do:**
+- ❌ Skip testing and assume it works
+- ❌ Make up test results
+- ❌ Silently ignore errors
+- ❌ Spend 30+ minutes debugging environmental issues
+
+## Handling Unexpected Test Results
+
+Sometimes the test runs but results don't match expectations.
+
+**Situations requiring pause:**
+
+1. **Test shows no difference WITH and WITHOUT PR**
+ - Might be testing wrong thing
+ - Might need different edge case
+ - **Action**: Use validation checkpoint to verify test setup
+
+2. **Test shows behavior got WORSE with PR**
+ - PR may introduce regression
+ - May be expected tradeoff
+ - **Action**: Flag in review, ask user if this is expected
+
+3. **Measurements seem wrong (all zeros, negative values, extreme values)**
+ - Layout may not have completed before measurement
+ - May need longer delay or different measurement timing
+ - **Action**: Add delay, remeasure, or ask for guidance
+
+4. **Crash or exception during test**
+ - PR may have introduced bug
+ - May be pre-existing issue
+ - **Action**: Test on baseline to determine if PR-related
+
+**Template for Unexpected Result Report**:
+
+```markdown
+## Unexpected Test Result
+
+**Test Scenario**: [What I tested]
+
+**Expected**: [What should have happened]
+
+**Actual**: [What actually happened]
+
+**WITH PR Changes**:
+```
+[Console output or measurements]
+```
+
+**WITHOUT PR Changes**:
+```
+[Baseline console output or measurements]
+```
+
+**Possible explanations**:
+1. [Hypothesis 1]
+2. [Hypothesis 2]
+
+**Need guidance on**:
+- Is this expected behavior?
+- Should I test differently?
+- Is this a PR regression?
+```
+
+**Why this matters**:
+
+❌ **Bad approach**: Silently ignore unexpected results and approve PR
+```
+Agent: "I tested it and everything works!" [but actually got confusing results]
+```
+
+✅ **Good approach**: Surface unexpected results for discussion
+```
+Agent: "I tested it but got unexpected results. Here's what I found: [data].
+ This could mean [explanation]. Should I investigate further or is this expected?"
+```
+
+**Rationale**: Better to pause and clarify than to approve a PR with hidden issues.
+
+## Handling Merge Conflicts
+
+When fetching the PR results in merge conflicts:
+
+**Template**:
+
+```markdown
+## Unable to Test: Merge Conflicts
+
+**Issue**: PR #XXXXX has merge conflicts with current branch
+
+**Conflicts in**:
+```bash
+# Output of git status
+[List of conflicting files]
+```
+
+**Recommendation**:
+- PR needs to be rebased on latest main/net10.0
+- Unable to test until conflicts are resolved
+- Author should run: `git rebase origin/main` (or origin/net10.0)
+
+**Review Status**: ⏸️ **Paused pending conflict resolution**
+```
+
+**What NOT to do**:
+- ❌ Try to manually resolve conflicts (not reviewer's job)
+- ❌ Test on outdated base branch
+- ❌ Approve PR with unresolved conflicts
diff --git a/.github/instructions/pr-reviewer-agent/output-format.md b/.github/instructions/pr-reviewer-agent/output-format.md
new file mode 100644
index 000000000000..b49dc5116331
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/output-format.md
@@ -0,0 +1,338 @@
+# Output Format and Review Structure
+
+## Review Output Format
+
+Structure your review in this order:
+
+```markdown
+## Summary
+[2-3 sentence overview of what the PR does and your assessment]
+
+## Code Review
+[Your analysis of the code changes - see core-guidelines.md for details]
+
+## Testing
+[Results from your manual testing with the Sandbox app]
+
+## Issues Found
+[Any problems, concerns, or questions - or "None" if everything looks good]
+
+## Recommendation
+✅ **Approve** - Ready to merge
+⚠️ **Request Changes** - Issues must be fixed
+💬 **Comment** - Feedback but not blocking
+⏸️ **Paused** - Cannot complete review (conflicts, environment issues, etc.)
+```
+
+## Final Review Step: Eliminate Redundancy
+
+**CRITICAL FINAL STEP**: Before posting your review, eliminate redundancy using this 6-step self-review process:
+
+### Step 1: Remove Repeated Test Details
+
+❌ **BAD - Repeating test details**:
+```markdown
+## Code Review
+The PR modifies `TextViewExtensions.cs` to fix RTL padding.
+
+## Testing
+I tested the RTL padding by creating a test with `FlowDirection.RightToLeft`.
+
+**Test Setup**:
+- Modified `MainPage.xaml` to add Label with `FlowDirection.RightToLeft`
+- Added Console.WriteLine for padding values
+- Built and deployed to iOS
+
+**Results WITHOUT PR**:
+Left padding: 0, Right padding: 10 ❌ (should be reversed)
+
+**Results WITH PR**:
+Left padding: 10, Right padding: 0 ✅
+
+The fix correctly reverses padding in RTL mode.
+
+## Issues Found
+None - the padding values are now correct in RTL mode.
+```
+
+✅ **GOOD - Information presented once**:
+```markdown
+## Code Review
+The PR modifies `TextViewExtensions.cs` to fix RTL padding by swapping left/right padding values when `FlowDirection.RightToLeft` is detected.
+
+## Testing
+
+**WITHOUT PR**: Left=0, Right=10 ❌ (padding on wrong side)
+**WITH PR**: Left=10, Right=0 ✅ (padding correctly reversed)
+
+Fix verified on iOS.
+
+## Issues Found
+None
+```
+
+### Step 2: Consolidate Platform-Specific Information
+
+❌ **BAD - Scattered platform mentions**:
+```markdown
+## Code Review
+The PR modifies iOS and Android code...
+
+## Testing
+I tested on iOS...
+
+## Issues Found
+The iOS fix looks good...
+The Android code also looks correct...
+```
+
+✅ **GOOD - Platform info consolidated**:
+```markdown
+## Code Review
+**Platforms affected**: iOS, Android
+
+The PR modifies `TextViewExtensions.cs` (Android) and `MauiLabel.cs` (iOS) to fix RTL padding.
+
+## Testing
+Verified on iOS (Android not tested due to emulator unavailability).
+
+## Issues Found
+None
+```
+
+### Step 3: Avoid Redundant Conclusions
+
+❌ **BAD - Saying "it works" multiple times**:
+```markdown
+## Code Review
+The code looks correct and should fix the issue.
+
+## Testing
+Test results show the fix works correctly.
+
+## Issues Found
+None - everything works as expected.
+
+## Recommendation
+✅ Approve - The fix is working correctly.
+```
+
+✅ **GOOD - State conclusion once**:
+```markdown
+## Code Review
+Code correctly implements RTL padding swap.
+
+## Testing
+Verified: padding values reversed correctly in RTL mode.
+
+## Issues Found
+None
+
+## Recommendation
+✅ Approve
+```
+
+### Step 4: Merge Related Findings
+
+❌ **BAD - Fragmented related issues**:
+```markdown
+## Issues Found
+
+**Issue 1**: No test coverage for FlowDirection.MatchParent
+**Issue 2**: Edge case not tested - what about nested RTL containers?
+**Issue 3**: Should also test with Margin property
+```
+
+✅ **GOOD - Grouped by theme**:
+```markdown
+## Issues Found
+
+**Missing test coverage**:
+- `FlowDirection.MatchParent` (edge case)
+- Nested RTL containers (complex scenario)
+- Interaction with Margin property
+```
+
+### Step 5: Remove Obvious Statements
+
+❌ **BAD - Stating the obvious**:
+```markdown
+## Summary
+This PR fixes a bug with RTL padding.
+
+## Code Review
+The PR modifies code to fix RTL padding issues.
+
+## Testing
+I tested the RTL padding fix to see if it works.
+```
+
+✅ **GOOD - Only necessary information**:
+```markdown
+## Summary
+PR correctly implements RTL padding swap for Label on iOS/Android.
+
+## Testing
+Verified padding values reverse correctly in RTL mode.
+```
+
+### Step 6: Self-Review Checklist
+
+Before posting, verify:
+
+- [ ] No information repeated in multiple sections
+- [ ] Platform-specific details consolidated
+- [ ] Conclusion stated once (not in every section)
+- [ ] Related issues grouped together
+- [ ] Obvious/redundant statements removed
+- [ ] Review reads smoothly without repetition
+
+**The goal**: Clear, concise review that respects the reader's time.
+
+## Examples to Avoid
+
+### Example 1: Extreme Redundancy
+
+❌ **This review repeats the same information 5 times**:
+
+```markdown
+## Summary
+This PR fixes RTL padding for Labels. The padding was on the wrong side in RTL mode.
+
+## Code Review
+The code changes fix the RTL padding issue by swapping left and right padding when in RTL mode.
+
+## Testing
+I tested the RTL padding fix. Before the PR, padding was on the wrong side in RTL mode.
+After the PR, padding is now on the correct side in RTL mode.
+
+**Test Results**:
+- WITHOUT PR: Padding on wrong side in RTL ❌
+- WITH PR: Padding on correct side in RTL ✅
+
+The RTL padding is now working correctly.
+
+## Issues Found
+None - the RTL padding issue is fixed.
+
+## Recommendation
+✅ Approve - The RTL padding fix works correctly
+```
+
+✅ **Same review without redundancy**:
+
+```markdown
+## Summary
+PR fixes RTL padding for Labels by swapping left/right values when `FlowDirection.RightToLeft`.
+
+## Code Review
+Correctly implements padding swap in `TextViewExtensions.cs` (Android) and `MauiLabel.cs` (iOS).
+
+## Testing
+**WITHOUT PR**: Left=0, Right=10 ❌
+**WITH PR**: Left=10, Right=0 ✅
+
+Verified on iOS.
+
+## Issues Found
+None
+
+## Recommendation
+✅ Approve
+```
+
+### Example 2: Scattered Information
+
+❌ **Information about testing scattered everywhere**:
+
+```markdown
+## Code Review
+I'll need to test this on iOS...
+
+## Testing
+I tested on iOS as mentioned above...
+
+## Issues Found
+As noted in testing, I couldn't test Android...
+
+## Recommendation
+Approve, though I couldn't test Android as I mentioned earlier...
+```
+
+✅ **Information organized by section**:
+
+```markdown
+## Code Review
+[Code analysis]
+
+## Testing
+Tested on iOS. Android not tested (no emulator available).
+
+## Issues Found
+None
+
+## Recommendation
+✅ Approve
+```
+
+## Consolidation Strategies
+
+**Strategy 1: Combine Test Setup and Results**
+
+Instead of:
+```markdown
+**Test Setup**: Created Label with FlowDirection.RightToLeft
+**Test Execution**: Built, deployed, and ran app
+**Test Results**: Padding values correct
+```
+
+Write:
+```markdown
+Verified with Label in RTL mode: padding values correctly reversed.
+```
+
+**Strategy 2: Use Bullet Points for Multiple Items**
+
+Instead of:
+```markdown
+Issue 1: Missing null check
+Issue 2: No test for edge case
+Issue 3: Documentation needed
+```
+
+Write:
+```markdown
+**Issues**:
+- Missing null check on line 47
+- No test for `FlowDirection.MatchParent` edge case
+- Public API needs XML documentation
+```
+
+**Strategy 3: Combine Related Code Comments**
+
+Instead of:
+```markdown
+Line 23: Good null check
+Line 24: Good error handling
+Line 25: Good logging
+```
+
+Write:
+```markdown
+Lines 23-25: Proper error handling with null check and logging.
+```
+
+## Final Note on Brevity
+
+**Remember**: Your review is likely one of many the PR author will read. Make every word count.
+
+- ✅ "RTL padding correctly reversed"
+- ❌ "The RTL padding values are now correctly reversed in RTL mode as they should be"
+
+- ✅ "Verified on iOS"
+- ❌ "I tested this on iOS and it works correctly"
+
+- ✅ "Missing null check (line 47)"
+- ❌ "I noticed that there's a missing null check on line 47 which could cause issues"
+
+**Shorter is better** as long as meaning is preserved.
diff --git a/.github/instructions/pr-reviewer-agent/safearea-guidelines.md b/.github/instructions/pr-reviewer-agent/safearea-guidelines.md
new file mode 100644
index 000000000000..92c564e9b25e
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/safearea-guidelines.md
@@ -0,0 +1,19 @@
+# SafeArea Testing Guidelines
+
+## Special Case: SafeArea Testing
+
+**If the PR modifies SafeAreaEdges, SafeAreaRegions, or related safe area handling code:**
+
+1. **CRITICAL: Read `.github/instructions/safearea-testing.instructions.md` FIRST** before setting up your test
+2. **Measure CHILD content position**, not the parent container with SafeAreaEdges
+3. **Calculate gaps from screen edges** to detect padding
+4. **Use colored backgrounds** (red parent, yellow child) for visual validation
+
+**Why this is critical**: SafeArea bugs are subtle. The parent container size stays constant - only the child content position changes. Measuring the wrong element will show no difference even when the bug exists.
+
+See `.github/instructions/safearea-testing.instructions.md` for comprehensive guidance including:
+- The "measure children, not parents" principle with visual diagrams
+- Complete XAML and instrumentation code examples
+- How to interpret gap measurements
+- Common mistakes to avoid
+- When to use the validation checkpoint for SafeArea testing
diff --git a/.github/instructions/pr-reviewer-agent/sandbox-setup.md b/.github/instructions/pr-reviewer-agent/sandbox-setup.md
new file mode 100644
index 000000000000..69011e66158c
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/sandbox-setup.md
@@ -0,0 +1,258 @@
+# Sandbox Setup and Instrumentation
+
+## Modify Sandbox App for Testing
+
+After fetching the PR, modify the Sandbox app to test the scenario.
+
+**File Locations**:
+- `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml` (UI layout)
+- `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml.cs` (code-behind)
+
+**General Instrumentation Pattern**:
+
+**MainPage.xaml** - Create visual test scenario:
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**MainPage.xaml.cs** - Capture measurements on Loaded:
+```csharp
+using Microsoft.Maui.Controls;
+
+namespace Maui.Controls.Sample
+{
+ public partial class MainPage : ContentPage
+ {
+ public MainPage()
+ {
+ InitializeComponent();
+ }
+
+ private void OnLoaded(object sender, EventArgs e)
+ {
+ // Wait for layout to complete
+ Dispatcher.DispatchDelayed(TimeSpan.FromMilliseconds(500), () =>
+ {
+ // Capture measurements
+ var element = (View)sender;
+ var bounds = element.Bounds;
+ var frame = element.Frame;
+
+ Console.WriteLine("=== TEST OUTPUT ===");
+ Console.WriteLine($"Element Bounds: {bounds}");
+ Console.WriteLine($"Element Frame: {frame}");
+ Console.WriteLine($"Element Y: {bounds.Y}");
+ Console.WriteLine($"Element Height: {bounds.Height}");
+ Console.WriteLine($"Screen Height: {DeviceDisplay.MainDisplayInfo.Height / DeviceDisplay.MainDisplayInfo.Density}");
+
+ // For nested content (SafeArea testing)
+ if (ContentLabel != null)
+ {
+ Console.WriteLine($"Content Bounds: {ContentLabel.Bounds}");
+ Console.WriteLine($"Content Y: {ContentLabel.Bounds.Y}");
+
+ // Calculate gaps from edges
+ double topGap = ContentLabel.Bounds.Y;
+ double screenHeight = DeviceDisplay.MainDisplayInfo.Height / DeviceDisplay.MainDisplayInfo.Density;
+ double bottomGap = screenHeight - (ContentLabel.Bounds.Y + ContentLabel.Bounds.Height);
+
+ Console.WriteLine($"Top Gap: {topGap}");
+ Console.WriteLine($"Bottom Gap: {bottomGap}");
+ }
+
+ Console.WriteLine("=== END TEST OUTPUT ===");
+ });
+ }
+ }
+}
+```
+
+**Key Instrumentation Techniques**:
+
+1. **Use `Console.WriteLine`** - Output is captured in test logs
+2. **Add markers** - "=== TEST OUTPUT ===" makes it easy to find in logs
+3. **Use `Loaded` event** - Ensures measurements happen after layout
+4. **Add delay** - `Dispatcher.DispatchDelayed(500ms)` ensures layout completed
+5. **Capture absolute position** - Not just size, but position from edges
+6. **Calculate gaps** - Especially for SafeArea testing (top/bottom gaps)
+7. **Color code elements** - Makes visual inspection easier (red parent, yellow child)
+8. **Measure correct elements** - Children positions, not parent sizes
+
+**Common Instrumentation Patterns**:
+
+**Pattern 1: Property Change Testing**
+```csharp
+// Test property toggle multiple times
+private async void OnLoaded(object sender, EventArgs e)
+{
+ Console.WriteLine("=== TEST: Property Toggle ===");
+
+ for (int i = 0; i < 5; i++)
+ {
+ TestElement.FlowDirection = FlowDirection.RightToLeft;
+ await Task.Delay(500);
+ Console.WriteLine($"Iteration {i}: RTL Bounds = {TestElement.Bounds}");
+
+ TestElement.FlowDirection = FlowDirection.LeftToRight;
+ await Task.Delay(500);
+ Console.WriteLine($"Iteration {i}: LTR Bounds = {TestElement.Bounds}");
+ }
+}
+```
+
+**Pattern 2: Nested Content Measurement**
+```csharp
+// Measure child within parent
+private void OnLoaded(object sender, EventArgs e)
+{
+ Console.WriteLine("=== TEST: Parent and Child ===");
+ Console.WriteLine($"Parent Bounds: {RootGrid.Bounds}");
+ Console.WriteLine($"Child Bounds: {ContentLabel.Bounds}");
+ Console.WriteLine($"Child Absolute Y: {ContentLabel.Bounds.Y + RootGrid.Bounds.Y}");
+}
+```
+
+**Pattern 3: Collection/List Testing**
+```csharp
+// Add large data set for scrolling test
+public MainPage()
+{
+ InitializeComponent();
+
+ var items = Enumerable.Range(1, 100).Select(i => $"Item {i}").ToList();
+ TestCollectionView.ItemsSource = items;
+}
+
+private void OnLoaded(object sender, EventArgs e)
+{
+ Console.WriteLine($"=== TEST: {TestCollectionView.ItemsSource.Count} items loaded ===");
+}
+```
+
+## Validation Checkpoint (WHEN to Use It)
+
+**What is the validation checkpoint?**
+- A pause in the review process where you show the user your test setup BEFORE running it
+- Allows the user to verify you're testing the right thing
+- Prevents wasting 20+ minutes on incorrect tests
+
+**When to use the validation checkpoint:**
+
+✅ **REQUIRED for these situations:**
+1. **SafeArea testing** - High risk of measuring the wrong element
+2. **First time testing a specific control type** - Unfamiliar with how to test it
+3. **Complex layout scenarios** - Nested controls, multiple layers
+4. **Unclear PR description** - Not certain what behavior to test
+5. **Multiple possible interpretations** - Could test in several different ways
+6. **After previous test attempt failed** - Need to adjust approach
+
+❌ **Skip validation checkpoint for:**
+- Simple, straightforward property tests (color, text, visibility)
+- Clear PR with obvious test scenario
+- Repetitive testing of same control type you've tested before
+- User explicitly said "just test it quickly"
+
+**What to show in validation checkpoint:**
+
+```markdown
+## Validation Checkpoint
+
+Before building and running the test (which takes time), I want to confirm my test setup:
+
+**Test Scenario**: [Describe what you're testing]
+
+**Sandbox Modifications**:
+```xml
+
+
+
+
+```
+
+```csharp
+// Show instrumentation code
+Console.WriteLine($"Content Y: {ContentLabel.Bounds.Y}");
+Console.WriteLine($"Top Gap: {topGap}");
+```
+
+**What I'm measuring**: [Explain what data you'll capture]
+- Content position from top edge (should show gap with SafeArea)
+- Content position from bottom edge (should show gap with SafeArea)
+
+**Why this approach**: [Justify why you're measuring these specific things]
+- SafeArea testing requires measuring child position, not parent size
+- Gaps from edges will show if padding is applied correctly
+
+**Does this test setup look correct?** If yes, I'll proceed with build/deploy/test. If not, please let me know what to adjust.
+```
+
+**Why validation checkpoint exists:**
+
+❌ **Problem without validation checkpoint:**
+```
+Agent: "Let me test this SafeArea fix..."
+[20 minutes of building, deploying, testing with WRONG measurements]
+Agent: "Here are the results: parent size is 400x800"
+User: "No, you should have measured the child position, not parent size"
+Agent: "Let me try again..."
+[Another 20 minutes wasted]
+```
+
+✅ **With validation checkpoint:**
+```
+Agent: "Let me test this SafeArea fix..."
+Agent: "Validation Checkpoint - I plan to measure child Y position and gaps"
+User: "Yes, that's correct" OR "No, also measure X position for RTL"
+Agent: [Builds and tests with CORRECT setup on first try]
+[20 minutes saved]
+```
+
+**Example Validation Checkpoint (SafeArea)**:
+
+```markdown
+## Validation Checkpoint - SafeArea Test Setup
+
+**Test Scenario**: Verify SafeArea respects Top and Bottom edges for Label within ContentView
+
+**Sandbox Setup**:
+- Red parent Grid (full screen)
+- Yellow ContentView with SafeAreaEdges="Top,Bottom"
+- Label inside ContentView
+
+**Measurements I'll capture**:
+1. `ContentLabel.Bounds.Y` - Position from ContentView top
+2. `TopGap` - Calculated as `ContentLabel.Bounds.Y`
+3. `BottomGap` - Calculated as `screenHeight - (Y + Height)`
+
+**Why measuring child, not parent**:
+- Per `.github/instructions/safearea-testing.instructions.md`, SafeArea affects child position
+- Parent ContentView size stays constant
+- Only child Label will be inset from edges
+
+**Expected Results**:
+- WITHOUT PR: Top gap should be ~0 (bug)
+- WITH PR: Top gap should be ~47px (status bar height)
+
+Does this test setup correctly validate the SafeArea fix?
+```
+
+**When user confirms**, proceed with build/deploy/test. If user corrects you, adjust the setup and show updated checkpoint.
diff --git a/.github/instructions/pr-reviewer-agent/testing-guidelines.md b/.github/instructions/pr-reviewer-agent/testing-guidelines.md
new file mode 100644
index 000000000000..22591b12d266
--- /dev/null
+++ b/.github/instructions/pr-reviewer-agent/testing-guidelines.md
@@ -0,0 +1,345 @@
+# Testing Guidelines
+
+## Which App to Use for Testing
+
+**CRITICAL DISTINCTION**: There are two testing apps in the repository, and choosing the wrong one wastes significant time (20+ minutes for unnecessary builds).
+
+**🟢 Sandbox App (`src/Controls/samples/Controls.Sample.Sandbox/`) - USE THIS FOR PR VALIDATION**
+
+**When to use**:
+- ✅ **DEFAULT**: Validating PR changes and testing scenarios
+- ✅ Reproducing the issue described in the PR
+- ✅ Testing edge cases not covered by the PR author
+- ✅ Comparing behavior WITH and WITHOUT PR changes
+- ✅ Instrumenting code to capture measurements
+- ✅ Any time you're validating if a fix actually works
+- ✅ Manual testing of the PR's scenario
+
+**Why**:
+- Builds in ~2 minutes (fast iteration)
+- Simple, empty app you can modify freely
+- Easy to instrument and capture measurements
+- Designed for quick testing and validation
+
+**🔴 TestCases.HostApp (`src/Controls/tests/TestCases.HostApp/`) - DO NOT USE FOR PR VALIDATION**
+
+**When to use**:
+- ❌ **NEVER** for validating PR changes or testing scenarios
+- ✅ **ONLY** when explicitly asked to write UI tests
+- ✅ **ONLY** when explicitly asked to validate UI tests
+- ✅ **ONLY** when running automated Appium tests via `dotnet test`
+
+**Why NOT to use for PR validation**:
+- Takes 20+ minutes to build for iOS (extremely slow)
+- Contains 100+ test pages (complex, hard to modify)
+- Designed for automated UI tests, not manual validation
+- Running automated tests is not part of PR review (that's what CI does)
+
+**Decision Tree**:
+
+```
+User asks to review PR #XXXXX
+ │
+ ├─ User explicitly says "write UI tests" or "validate the UI tests"?
+ │ └─ YES → Use TestCases.HostApp (and TestCases.Shared.Tests)
+ │
+ └─ Otherwise (normal PR review with testing)?
+ └─ Use Sandbox app for validation
+```
+
+**Examples**:
+
+✅ **Use Sandbox app**:
+- "Review PR #32372"
+- "Validate the RTL CollectionView fix"
+- "Test this SafeArea change on iOS"
+- "Review and test this PR"
+- "Does this fix actually work?"
+- "Compare before/after behavior"
+
+❌ **Use TestCases.HostApp** (only for these explicit requests):
+- "Write UI tests for this PR"
+- "Validate the UI tests in this PR work correctly"
+- "Run the automated UI tests"
+- "Create an Issue32372.xaml test page"
+
+**Rule of Thumb**:
+- **Validating the PR's fix** = Sandbox app (99% of reviews)
+- **Writing/validating automated tests** = TestCases.HostApp (1% of reviews, only when explicitly asked)
+
+## Fetch PR Changes (Without Checking Out)
+
+**CRITICAL**: Stay on your current branch (wherever you are when starting the review) to preserve context. Apply PR changes on top of the current branch instead of checking out the PR branch.
+
+**FIRST STEP - Record Your Starting Branch:**
+```bash
+# Record what branch you're currently on - you'll need this for cleanup
+ORIGINAL_BRANCH=$(git branch --show-current)
+echo "Starting review from branch: $ORIGINAL_BRANCH"
+# Remember this value for cleanup at the end!
+```
+
+```bash
+# Get the PR number from the user's request
+PR_NUMBER=XXXXX # Replace with actual PR number
+
+# Fetch the PR into a temporary branch
+git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER-temp
+
+# Check fetch succeeded
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: Failed to fetch PR #$PR_NUMBER"
+ exit 1
+fi
+
+# Create a test branch from current branch (preserves instruction files)
+git checkout -b test-pr-$PR_NUMBER
+
+# Check branch creation succeeded
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: Failed to create test branch"
+ exit 1
+fi
+
+# Merge the PR changes into the test branch
+git merge pr-$PR_NUMBER-temp -m "Test PR #$PR_NUMBER" --no-edit
+
+# Check merge succeeded (will error if conflicts)
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: Merge failed with conflicts"
+ echo "See section below on handling merge conflicts"
+ exit 1
+fi
+```
+
+**If merge conflicts occur:**
+```bash
+# See which files have conflicts
+git status
+
+# For simple conflicts, you can often accept the PR's version
+git checkout --theirs
+git add
+
+# Complete the merge
+git commit --no-edit
+```
+
+**Why this approach:**
+- ✅ Preserves your current working context and branch state
+- ✅ Tests PR changes on top of wherever you currently are
+- ✅ Allows agent to maintain proper context across review
+- ✅ Easy to clean up (just delete test branch and return to original branch)
+- ✅ Can compare before/after easily
+- ✅ Handles most conflicts gracefully
+
+## Setup Test Environment
+
+**iOS Testing**:
+```bash
+# Find iPhone Xs with highest iOS version
+UDID=$(xcrun simctl list devices available --json | jq -r '.devices | to_entries | map(select(.key | startswith("com.apple.CoreSimulator.SimRuntime.iOS"))) | map({key: .key, version: (.key | sub("com.apple.CoreSimulator.SimRuntime.iOS-"; "") | split("-") | map(tonumber)), devices: .value}) | sort_by(.version) | reverse | map(select(.devices | any(.name == "iPhone Xs"))) | first | .devices[] | select(.name == "iPhone Xs") | .udid')
+
+# Check UDID was found
+if [ -z "$UDID" ] || [ "$UDID" = "null" ]; then
+ echo "❌ ERROR: No iPhone Xs simulator found. Please create one."
+ exit 1
+fi
+
+# Boot simulator
+xcrun simctl boot $UDID 2>/dev/null || true
+
+# Check simulator is booted
+STATE=$(xcrun simctl list devices --json | jq -r --arg udid "$UDID" '.devices[][] | select(.udid == $udid) | .state')
+if [ "$STATE" != "Booted" ]; then
+ echo "❌ ERROR: Simulator failed to boot. Current state: $STATE"
+ exit 1
+fi
+```
+
+**Android Testing**:
+
+**CRITICAL**: If starting an emulator, use the background daemon pattern from [Common Testing Patterns: Android Emulator Startup](../../instructions/common-testing-patterns.md#android-emulator-startup-with-error-checking) to ensure it persists across sessions.
+
+```bash
+# Get connected device/emulator
+export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1)
+
+# Check device was found
+if [ -z "$DEVICE_UDID" ]; then
+ echo "❌ ERROR: No Android device/emulator found. Start an emulator or connect a device."
+ exit 1
+fi
+```
+
+**Important Android Rules**:
+- ✅ **Start emulators with subshell + background**: `cd $ANDROID_HOME/emulator && (./emulator -avd Name ... &)`
+- ❌ **NEVER use `adb kill-server`** - This disconnects active emulators and is almost never needed
+- ❌ **NEVER use `mode="async"` for emulators** - They will be killed when the session ends
+- ✅ **Check `adb devices` first** - If device is visible, no action needed
+
+## Build and Deploy
+
+**iOS**:
+```bash
+# Build
+dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-ios
+
+# Check build succeeded
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: Build failed"
+ exit 1
+fi
+
+# Install
+xcrun simctl install $UDID artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app
+
+# Check install succeeded
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: App installation failed"
+ exit 1
+fi
+
+# Launch with console capture
+xcrun simctl launch --console-pty $UDID com.microsoft.maui.sandbox > /tmp/ios_test.log 2>&1 &
+
+# Check launch didn't immediately fail
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: App launch failed"
+ exit 1
+fi
+
+sleep 8
+cat /tmp/ios_test.log
+```
+
+**Android**:
+```bash
+# Build and deploy
+dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-android -t:Run
+
+# Check build/deploy succeeded
+if [ $? -ne 0 ]; then
+ echo "❌ ERROR: Build or deployment failed"
+ exit 1
+fi
+
+# Monitor logs
+adb logcat | grep -E "(YourMarker|Frame|Console)"
+```
+
+## Success Verification Points
+
+After each major step, verify success before proceeding to the next step:
+
+**After PR Fetch:**
+- ✅ Confirm branch `test-pr-[NUMBER]` exists: `git branch --list test-pr-*`
+- ✅ Verify PR commits are present: `git log --oneline -5`
+- ✅ Check you're on the test branch: `git branch --show-current`
+
+**After Sandbox Modification:**
+- ✅ Files modified: `MainPage.xaml` and `MainPage.xaml.cs`
+- ✅ Instrumentation code includes `Console.WriteLine` statements
+- ✅ Test scenario matches PR description
+- ✅ If uncertain about test approach, consider using validation checkpoint
+
+**After Build:**
+- ✅ Build succeeded with no errors (warnings are OK)
+- ✅ Artifact exists:
+ - iOS: `artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app`
+ - Android: `artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-android/*/com.microsoft.maui.sandbox-Signed.apk`
+- ✅ No "0 succeeded, 1 failed" in build output
+
+**After Deploy & Run:**
+- ✅ App launched successfully (no crash on startup)
+- ✅ Console output captured in log file or terminal
+- ✅ Instrumentation output is visible in logs (search for "TEST OUTPUT" or your marker)
+- ✅ Measurements show reasonable values (not all zeros or nulls)
+
+**If any verification fails:**
+- 🛑 **STOP immediately**
+- 📝 Document what failed and the error message
+- 🔍 Attempt to fix (1-2 attempts maximum)
+- ❓ If still failing, ask for help
+
+## Test WITH and WITHOUT PR Changes
+
+1. **First**: Test WITHOUT PR changes
+ ```bash
+ # On test-pr-XXXXX branch, temporarily revert the PR commits
+ # Identify how many commits came from the PR
+ NUM_COMMITS=$(git log --oneline pr-reviewer..HEAD | wc -l)
+
+ # Create a temporary branch at the commit before PR changes
+ git checkout -b baseline-test HEAD~$NUM_COMMITS
+
+ # Build and test to capture baseline data
+ ```
+
+2. **Capture baseline data** (build, deploy, run with instrumentation)
+
+3. **Then**: Test WITH PR changes
+ ```bash
+ # Switch back to test branch with PR changes
+ git checkout test-pr-XXXXX
+
+ # Build and test with PR changes
+ ```
+
+4. **Capture new data** (build, deploy, run with instrumentation)
+
+5. **Compare results** and include in review
+
+6. **Clean up test branches**
+ ```bash
+ # Return to original branch (whatever branch you started on)
+ git checkout $ORIGINAL_BRANCH
+
+ # Delete test branches
+ git branch -D test-pr-XXXXX baseline-test pr-XXXXX-temp
+ ```
+
+ **Note**: Uses `$ORIGINAL_BRANCH` variable you set at the beginning. If you didn't save it, replace with whatever branch you were on when you started the review (e.g., `main`, `pr-reviewer`, etc.)
+
+## Include Test Results in Review
+
+Format test data clearly:
+
+```markdown
+## Test Results
+
+**Environment**: iOS 26.0 (iPhone 17 Pro Simulator)
+**Test Scenario**: [Description]
+
+**WITHOUT PR (Current Main)**:
+```
+[Actual console output or measurements]
+```
+❌ Issue: [What's wrong]
+
+**WITH PR Changes**:
+```
+[Actual console output or measurements]
+```
+✅ Result: [What changed]
+```
+
+## Cleanup
+
+After testing, clean up all test artifacts:
+
+```bash
+# Return to your original branch (use the variable from the beginning)
+git checkout $ORIGINAL_BRANCH # Or manually specify: main, pr-reviewer, etc.
+
+# Revert any changes to Sandbox app
+git checkout -- src/Controls/samples/Controls.Sample.Sandbox/
+
+# Delete test branches
+git branch -D test-pr-XXXXX baseline-test pr-XXXXX-temp 2>/dev/null || true
+
+# Clean build artifacts if needed
+dotnet clean
+```
+
+**Important**: If you didn't save `$ORIGINAL_BRANCH` at the start, replace it with whatever branch you were on when you began the review. This ensures you return to your starting state.
diff --git a/.github/prompts/pr-reviewer.prompt.md b/.github/prompts/pr-reviewer.prompt.md
index a05669447b72..858f0aa4f5d6 100644
--- a/.github/prompts/pr-reviewer.prompt.md
+++ b/.github/prompts/pr-reviewer.prompt.md
@@ -1,62 +1,149 @@
-# PR Reviewer - Quick Reference
-
-The `pr-reviewer` agent conducts thorough code reviews with hands-on device/simulator testing and validation.
-
-## How It Works
-
-The agent always performs **thorough reviews** which include:
-
-1. **Code Analysis** - Review code for correctness, style, and best practices
-2. **Build & Deploy** - Build the Sandbox app and deploy to simulator/emulator
-3. **Real Testing** - Test the PR changes on actual devices with measurements
-4. **Before/After Comparison** - Compare behavior with and without PR changes
-5. **Edge Case Testing** - Test scenarios not mentioned by the PR author
-6. **Documented Results** - Provide review with actual test data and evidence
+---
+description: "Conduct thorough PR reviews with hands-on testing on real devices/simulators"
+name: pr-reviewer
+agent: pr-reviewer
+---
+
+# PR Reviewer
+
+Reviews .NET MAUI pull requests through code analysis AND hands-on device testing with instrumentation.
+
+## What It Does
+
+**Thorough Testing-Based Reviews:**
+1. 📖 Fetches and analyzes PR changes
+2. 🏗️ Builds Sandbox app with PR modifications
+3. 📱 Deploys to iOS/Android simulators
+4. 🔬 Uses **Appium** for reliable UI interaction (never manual ADB commands)
+5. 📊 Instruments code to capture actual measurements
+6. ⚖️ Compares WITH/WITHOUT PR changes
+7. 🧪 Tests edge cases PR author may have missed
+8. 📝 Documents findings with real data
+
+**Key Principles:**
+- ✅ Uses **Sandbox app** for validation (not TestCases.HostApp)
+- ✅ Uses **Appium** for ALL UI interactions (taps, swipes, rotations)
+- ✅ Uses **background daemon pattern** for Android emulators (survives sessions)
+- ✅ Never kills ADB server unnecessarily
+- ✅ Pauses and asks for help if stuck (never gives up and switches to code-only review)
## Usage Examples
**Basic review:**
```
-Please review PR #32372
+/pr-reviewer Please review PR #32372
```
-**Platform-specific testing:**
+**Platform-specific:**
```
-Test PR #32205 on iOS 26.0 specifically
+/pr-reviewer Test PR #32205 on iOS 26.0
```
**Cross-platform validation:**
```
-Test PR #12345 on both iOS and Android to verify cross-platform behavior
+/pr-reviewer Validate PR #12345 on both iOS and Android
```
-**Margin/Layout Issues:**
+**Layout/SafeArea issues:**
```
-Review PR #32205 and instrument the Sandbox app to capture actual frame positions
+/pr-reviewer Review PR #32275 and test Shell flyout in landscape with display notch
```
-**Before/After Comparison:**
+**Specific scenario:**
```
-Test PR #32205 comparing behavior WITH and WITHOUT the changes
+/pr-reviewer Test PR #32205 with RTL layout and capture frame measurements
```
-## What Happens If Build Fails?
+**Before/after comparison:**
+```
+/pr-reviewer Compare behavior WITH and WITHOUT PR #12345 changes
+```
-If the agent encounters build errors during testing:
+## What You'll Get
+
+**Comprehensive Review Document** (`Review_Feedback_Issue_XXXXX.md`) including:
+
+- ✅ **Code Analysis** - Style, correctness, best practices review
+- ✅ **Test Environment** - Platform/version/device used
+- ✅ **Actual Measurements** - Console output, frame positions, inset values
+- ✅ **Before/After Comparison** - Behavior with and without PR
+- ✅ **Edge Cases** - Additional scenarios tested beyond PR description
+- ✅ **Screenshots** - Visual evidence when relevant
+- ✅ **Issues Found** - Problems discovered through testing
+- ✅ **Recommendations** - Accept/reject/modify based on evidence
+
+## Expectations
+
+**Timeline:**
+- ⏱️ Reviews take 15-45 minutes (building, deploying, testing multiple scenarios)
+- ✅ Agent has **unlimited time** - will not rush or skip testing
+- ✅ You'll see progress updates as testing proceeds
+
+**Testing Approach:**
+- 🤖 **Appium-based** - All UI automation through Appium (reliable, verifiable)
+- 📱 **Real devices** - Tests on actual iOS simulators or Android emulators
+- 📏 **Instrumented** - Adds logging to capture measurements
+- 🔄 **Comparative** - Tests both with and without PR changes
+
+**If Issues Occur:**
+- Build fails → Agent attempts 1-2 fixes, then **pauses** for your input
+- Emulator crashes → Agent reports issue and asks for guidance
+- Unexpected behavior → Agent documents and asks for validation
+- **Never silently falls back to code-only review**
+
+## Common Scenarios
+
+**SafeArea/Layout PRs:**
+- Agent instruments views to capture padding, margins, frame positions
+- Tests in portrait and landscape orientations
+- Verifies safe area insets are applied correctly
+- Measures child vs parent view positions
+
+**UI Component PRs:**
+- Opens Sandbox app with test scenario
+- Uses Appium to interact with controls (taps, swipes, text entry)
+- Captures screenshots and measurements
+- Tests on target platform (iOS, Android, or both)
+
+**Shell/Navigation PRs:**
+- Sets up Shell in Sandbox with flyout items
+- Uses Appium to open menus, navigate, test gestures
+- Verifies behavior in different orientations
+- Tests with and without headers/footers
+
+**Cross-Platform PRs:**
+- Tests same scenario on iOS AND Android
+- Compares platform-specific behavior
+- Verifies consistent user experience
+- Notes any platform differences
+
+## Tips for Best Results
+
+✅ **Be specific** about what to test:
+```
+/pr-reviewer Test PR #12345 focusing on RTL layout behavior
+```
-1. It will try to fix obvious issues (1-2 attempts)
-2. If errors persist, it will **STOP** and ask for your help
-3. It will **NOT** silently switch to code-only review
-4. You'll get a clear error report with options to proceed
+✅ **Mention platform** if it matters:
+```
+/pr-reviewer Test PR #32275 on Android with display notch
+```
-This ensures you always know when testing couldn't be completed.
+✅ **Request measurements** for layout issues:
+```
+/pr-reviewer Capture actual frame positions and padding values for PR #32205
+```
+
+✅ **Ask for edge cases**:
+```
+/pr-reviewer Test PR #12345 including rotation, RTL, and empty state scenarios
+```
-## Expected Output
+❌ **Don't rush the agent** - Testing takes time, and thoroughness prevents bugs
-Every review includes:
+## Related Resources
-- **Test Results** - Actual console output and measurements from simulator/device
-- **Environment Details** - Which platform/version was tested
-- **Comparison** - Behavior with and without PR changes
-- **Issues & Suggestions** - Validated through real testing
-- **Recommendation** - Based on both code review and hands-on validation
+- [Core Guidelines](.github/instructions/pr-reviewer-agent/core-guidelines.md) - Full workflow details
+- [Testing Guidelines](.github/instructions/pr-reviewer-agent/testing-guidelines.md) - Platform setup, build patterns
+- [Appium Instructions](.github/instructions/appium-control.instructions.md) - UI automation patterns
+- [Common Testing Patterns](.github/instructions/common-testing-patterns.md) - Device setup, error checking
diff --git a/Review_Feedback_Issue_12156.md b/Review_Feedback_Issue_12156.md
new file mode 100644
index 000000000000..1f586392992f
--- /dev/null
+++ b/Review_Feedback_Issue_12156.md
@@ -0,0 +1,290 @@
+# PR Review: #32081 - [iOS] Added support for large titles in Shell
+
+**PR**: https://github.com/dotnet/maui/pull/32081
+**Issue**: https://github.com/dotnet/maui/issues/12156
+**Reviewer**: GitHub Copilot PR Reviewer
+**Review Date**: 2025-11-20
+
+## Summary
+
+PR #32081 implements iOS large navigation bar titles in Shell by adding `UpdateLargeTitles()` to `ShellItemRenderer.cs`. The implementation correctly maps .NET MAUI's `LargeTitleDisplayMode` to iOS `UINavigationItemLargeTitleDisplayMode`.
+
+**Status**: ✅ Excellent implementation with minor cosmetic cleanup suggested
+
+**Core implementation**: ✅ Solid - proper null checks, iOS version guard, correct enum mapping, appropriate lifecycle hooks
+**Test coverage**: ✅ Well-structured with screenshot verification, has minor redundancy in preprocessor directive
+
+---
+
+## Code Review
+
+### ✅ Positive Aspects
+
+1. **Correct iOS version check**
+ - Uses `OperatingSystem.IsIOSVersionAtLeast(11)` (large titles introduced in iOS 11)
+ - Prevents crashes on older iOS versions
+
+2. **Proper null safety**
+ - Checks `page is null` before proceeding
+ - Checks `navigationController` and `top` before accessing
+
+3. **Appropriate lifecycle hooks**
+ - Called in `OnDisplayedPageChanged()` when page changes
+ - Called in `ViewWillLayoutSubviews()` to ensure state consistency
+
+4. **Correct enum mapping**
+ ```csharp
+ LargeTitleDisplayMode.Always => UINavigationItemLargeTitleDisplayMode.Always,
+ LargeTitleDisplayMode.Automatic => UINavigationItemLargeTitleDisplayMode.Automatic,
+ _ => UINavigationItemLargeTitleDisplayMode.Never
+ ```
+
+5. **Sets both required properties**
+ - `NavigationBar.PrefersLargeTitles` (enables feature)
+ - `NavigationItem.LargeTitleDisplayMode` (per-page control)
+
+6. **Follows existing patterns**
+ - Mirrors `UpdateTabBarHidden()` implementation
+ - Consistent with Shell handler architecture
+
+---
+
+## 🟡 Minor Issues
+
+### 1. Redundant Conditional Compilation
+
+**File**: `src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue12156.cs`
+**Line**: 1
+
+**Issue**:
+```csharp
+#if TEST_FAILS_ON_ANDROID && TEST_FAILS_ON_ANDROID && TEST_FAILS_ON_WINDOWS
+```
+
+`TEST_FAILS_ON_ANDROID` appears twice - this is redundant but harmless.
+
+**How it works**: The test project system defines constants for platforms where tests SHOULD NOT run:
+- iOS.Tests defines: `TEST_FAILS_ON_ANDROID`, `TEST_FAILS_ON_WINDOWS`, `TEST_FAILS_ON_CATALYST`
+- Android.Tests defines: `TEST_FAILS_ON_IOS`, `TEST_FAILS_ON_WINDOWS`, `TEST_FAILS_ON_CATALYST`
+
+So this condition:
+- iOS tests: TRUE && TRUE && TRUE = TRUE → test runs ✅
+- Android tests: FALSE && FALSE && TRUE = FALSE → test skipped ✅
+- Windows tests: FALSE && FALSE && FALSE = FALSE → test skipped ✅
+
+**Fix** (optional cleanup):
+```csharp
+#if TEST_FAILS_ON_ANDROID && TEST_FAILS_ON_WINDOWS // Remove duplicate
+```
+
+**Impact**: LOW - Code compiles and runs correctly, just has a cosmetic redundancy
+
+---
+
+## 🟡 Suggestions for Improvement
+
+### 1. Missing Dynamic Property Change Handling
+
+**Current behavior**: `UpdateLargeTitles()` is only called when:
+- Displayed page changes (`OnDisplayedPageChanged`)
+- View lays out subviews (`ViewWillLayoutSubviews`)
+
+**Gap**: If a user changes `Page.LargeTitleDisplay` property dynamically at runtime (e.g., in response to user action), the navigation bar won't update.
+
+**Comparison**: `OnDisplayedPagePropertyChanged` only listens for `Shell.TabBarIsVisibleProperty`:
+```csharp
+void OnDisplayedPagePropertyChanged(object sender, PropertyChangedEventArgs e)
+{
+ if (e.PropertyName == Shell.TabBarIsVisibleProperty.PropertyName)
+ UpdateTabBarHidden();
+ // Missing: Check for LargeTitleDisplay property changes
+}
+```
+
+**Suggested improvement**:
+```csharp
+void OnDisplayedPagePropertyChanged(object sender, PropertyChangedEventArgs e)
+{
+ if (e.PropertyName == Shell.TabBarIsVisibleProperty.PropertyName)
+ UpdateTabBarHidden();
+ else if (e.PropertyName == PlatformConfiguration.iOSSpecific.Page.LargeTitleDisplayProperty.PropertyName)
+ UpdateLargeTitles();
+}
+```
+
+**Impact**: MEDIUM - Users might want to toggle this dynamically (though uncommon)
+
+---
+
+### 2. Performance Consideration - ViewWillLayoutSubviews
+
+**Observation**: `UpdateLargeTitles()` is called in `ViewWillLayoutSubviews()`, which executes on every layout pass (very frequently).
+
+**Analysis**:
+- Setting navigation bar properties repeatedly could be inefficient
+- However, `UpdateTabBarHidden()` already uses this pattern
+- iOS likely optimizes no-op property sets
+
+**Potential optimization** (optional):
+```csharp
+LargeTitleDisplayMode? _lastLargeTitleDisplayMode;
+
+void UpdateLargeTitles()
+{
+ var page = _displayedPage;
+ if (page is null || !OperatingSystem.IsIOSVersionAtLeast(11))
+ return;
+
+ var largeTitleDisplayMode = page.OnThisPlatform().LargeTitleDisplay();
+
+ // Only update if changed
+ if (_lastLargeTitleDisplayMode == largeTitleDisplayMode)
+ return;
+
+ _lastLargeTitleDisplayMode = largeTitleDisplayMode;
+
+ // ... rest of implementation
+}
+```
+
+**Impact**: LOW - Likely not a real performance issue, iOS handles repeated property sets efficiently
+
+---
+
+### 3. Test Coverage Gaps
+
+**Current test**:
+- Only tests `LargeTitleDisplay="Always"`
+- Uses screenshot verification (good)
+- Simple single-page Shell
+
+**Missing scenarios**:
+1. `LargeTitleDisplay="Never"` - should show regular title
+2. `LargeTitleDisplay="Automatic"` - should follow system behavior
+3. Multi-page navigation - title mode changes when navigating
+4. Dynamic property changes - changing mode at runtime
+5. Shell with multiple tabs - each tab can have different modes
+
+**Suggested additional tests** (future enhancement):
+```csharp
+[Test]
+public void LargeTitleDisplayNever()
+{
+ // Verify standard title bar height
+}
+
+[Test]
+public void LargeTitleDisplayAutomatic()
+{
+ // Verify automatic behavior (large on first page, small after scroll/navigation)
+}
+```
+
+**Impact**: MEDIUM - Current test validates basic functionality, but edge cases untested
+
+---
+
+## 🛑 Testing Status - CHECKPOINT REQUIRED
+
+### Environment Limitation
+
+**Issue**: PR review is being performed in a Linux environment without iOS simulators.
+**Required**: iOS simulator or physical device to validate:
+1. Large title actually displays correctly
+2. Title size changes between Always/Never/Automatic modes
+3. Navigation between pages preserves settings
+4. No visual glitches or layout issues
+
+### Checkpoint for iOS Testing
+
+**Platform**: iOS 17+ (iPhone Xs or later recommended)
+**Why needed**: Visual validation of large title behavior requires running on iOS
+
+**Testing steps needed**:
+
+1. **Build Sandbox app with test scenario**:
+ ```bash
+ # Modify src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml to:
+ # - Create a Shell with LargeTitleDisplay="Always"
+ # - Add navigation button to test with LargeTitleDisplay="Never"
+ # - Add another button for "Automatic" mode
+
+ # Build for iOS
+ dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-ios
+
+ # Install to simulator
+ xcrun simctl install $UDID artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app
+
+ # Launch and capture screenshots
+ xcrun simctl launch --console-pty $UDID com.microsoft.maui.sandbox
+ ```
+
+2. **Visual verification**:
+ - Screenshot with `LargeTitleDisplay="Always"` - title should be LARGE
+ - Screenshot with `LargeTitleDisplay="Never"` - title should be regular size
+ - Screenshot with `LargeTitleDisplay="Automatic"` - title should be large initially
+ - Navigate to second page - verify title behavior changes as expected
+
+3. **Edge case testing**:
+ - Change property dynamically at runtime (if implemented)
+ - Navigate back and forth between pages
+ - Switch between Shell tabs (if multi-tab)
+
+**Resume instructions**: After iOS testing is complete, update this review document with:
+- Test results (pass/fail for each scenario)
+- Screenshots showing large title vs regular title
+- Any visual issues discovered
+
+---
+
+## Current Recommendation
+
+✅ **Approve with Optional Improvements**
+
+### Optional Cleanup (Non-Blocking)
+
+1. 🟡 **Remove redundant condition** in UI test (Line 1 of Issue12156.cs)
+ - Current: `#if TEST_FAILS_ON_ANDROID && TEST_FAILS_ON_ANDROID && TEST_FAILS_ON_WINDOWS`
+ - Cleaner: `#if TEST_FAILS_ON_ANDROID && TEST_FAILS_ON_WINDOWS`
+ - **Impact**: Cosmetic only - code works correctly either way
+
+### Recommended Improvements (Non-Blocking)
+
+1. 🟡 Add property change listener for dynamic `LargeTitleDisplay` updates (see suggestion above)
+2. 🟡 Expand test coverage to include Never/Automatic modes (future enhancement)
+3. 🟡 Consider caching last display mode to avoid redundant property sets (optional performance optimization)
+
+---
+
+## Post-iOS-Testing Update
+
+**iOS testing status**: Unable to complete due to Linux environment limitation (no iOS simulators available)
+
+**Recommendation without iOS testing**: Based on code review alone, the implementation appears correct:
+- Proper use of iOS APIs
+- Correct lifecycle integration
+- Appropriate null safety and version checks
+- Follows established patterns in the codebase
+
+**Ideal validation** (when iOS environment is available):
+1. Visual confirmation that large titles display correctly
+2. Verification of Always/Never/Automatic modes
+3. Test navigation between pages with different settings
+4. Confirm no visual glitches or layout issues
+
+**Current recommendation**: ✅ **Approve** - Code quality is excellent, iOS testing would provide additional confidence but is not blocking
+
+---
+
+## Related Documentation
+
+- [iOS Large Title Documentation](https://developer.apple.com/design/human-interface-guidelines/ios/bars/navigation-bars/)
+- [UINavigationBar.prefersLargeTitles](https://developer.apple.com/documentation/uikit/uinavigationbar/2908999-preferslargetitles)
+- [.NET MAUI Platform Specifics - iOS](https://learn.microsoft.com/dotnet/maui/platform-integration/platform-specifics)
+
+---
+
+## Review History
+
+- **2025-11-20**: Initial code review complete, iOS testing checkpoint created
+- **Pending**: iOS simulator validation