Add public IImageSourcePaint contract for external platform backends

MAUI represents an image background as the internal `ImageSourcePaint`
type. Out-of-tree platform backends receive backgrounds as a `Paint` via
`IView.Background`, so they cannot detect an image background or read its
`IImageSource` without reflection or `InternalsVisibleTo`.

Adds a minimal, additive public contract, `Microsoft.Maui.IImageSourcePaint`,
exposing a single read-only `ImageSource` property. The internal
`ImageSourcePaint` now implements it, and every in-tree consumer pattern
matches on the interface instead of the concrete type.

This is purely additive:
- `ImageSourcePaint` stays internal, so no implementation detail is exposed.
- No brush/paint API, XAML, or serialization surface changes; `ImageBrush`
  round-trips exactly as before.
- Interface pattern matching is trim/AOT safe and adds no reflection.
- Equality and built-in platform behavior are unchanged.

Because in-tree handlers now match the interface, a backend (or app) can
also supply its own `Paint` implementing `IImageSourcePaint` and have the
built-in handlers render it as an image background.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5ec0bf62-da2c-49fb-af27-a0a79cbbd6bb

Author: Redth

src/Controls/src/Core/Brush/Brush.cs

@@ -52,7 +52,7 @@ public static implicit operator Brush(Paint paint)
 				}
 			}
 
-			if (paint is ImageSourcePaint imageSourcePaint && imageSourcePaint.ImageSource is ImageSource imageSource)
+			if (paint is IImageSourcePaint imageSourcePaint && imageSourcePaint.ImageSource is ImageSource imageSource)
 				return new ImageBrush { ImageSource = imageSource };
 
 			return null;

src/Controls/tests/Core.UnitTests/ImageBrushTests.cs

@@ -0,0 +1,57 @@
+using Microsoft.Maui.Graphics;
+using Xunit;
+
+namespace Microsoft.Maui.Controls.Core.UnitTests
+{
+	public class ImageBrushTests : BaseTestFixture
+	{
+		[Fact]
+		public void ImageBrushConvertsToImageSourcePaint()
+		{
+			var imageSource = ImageSource.FromFile("background.png");
+
+			Paint paint = new ImageBrush { ImageSource = imageSource };
+
+			var imagePaint = Assert.IsAssignableFrom<IImageSourcePaint>(paint);
+			Assert.Same(imageSource, imagePaint.ImageSource);
+		}
+
+		[Fact]
+		public void ImageSourcePaintConvertsBackToImageBrush()
+		{
+			var imageSource = ImageSource.FromFile("background.png");
+
+			Paint paint = new ImageBrush { ImageSource = imageSource };
+			Brush brush = (Brush)paint;
+
+			var imageBrush = Assert.IsType<ImageBrush>(brush);
+			Assert.Same(imageSource, imageBrush.ImageSource);
+		}
+
+		[Fact]
+		public void ExternalImageSourcePaintConvertsToImageBrush()
+		{
+			var imageSource = ImageSource.FromFile("background.png");
+
+			Brush brush = (Brush)new ExternalImageSourcePaint(imageSource);
+
+			var imageBrush = Assert.IsType<ImageBrush>(brush);
+			Assert.Same(imageSource, imageBrush.ImageSource);
+		}
+
+		[Fact]
+		public void SolidAndGradientPaintsAreNotImageSourcePaints()
+		{
+			Assert.IsNotAssignableFrom<IImageSourcePaint>((Paint)new SolidColorBrush(Colors.Red));
+			Assert.IsNotAssignableFrom<IImageSourcePaint>((Paint)new LinearGradientBrush());
+			Assert.IsNotAssignableFrom<IImageSourcePaint>((Paint)new RadialGradientBrush());
+		}
+
+		class ExternalImageSourcePaint : Paint, IImageSourcePaint
+		{
+			public ExternalImageSourcePaint(IImageSource imageSource) => ImageSource = imageSource;
+
+			public IImageSource ImageSource { get; }
+		}
+	}
+}

src/Core/src/Handlers/Editor/EditorHandler.iOS.cs

@@ -144,7 +144,7 @@ public static void MapBackground(IEditorHandler handler, IEditor editor)
 			if (handler.PlatformView is not MauiTextView platformView)
 				return;
 
-			if (editor.Background is ImageSourcePaint image)
+			if (editor.Background is IImageSourcePaint image)
 			{
 				var provider = handler.GetRequiredService<IImageSourceServiceProvider>();
 				platformView.UpdateBackgroundImageSourceAsync(image.ImageSource, provider)

src/Core/src/Handlers/Entry/EntryHandler.iOS.cs

@@ -53,7 +53,7 @@ public static void MapBackground(IEntryHandler handler, IEntry entry)
 			if (handler.PlatformView is not MauiTextField platformView)
 				return;
 
-			if (entry.Background is ImageSourcePaint image)
+			if (entry.Background is IImageSourcePaint image)
 			{
 				var provider = handler.GetRequiredService<IImageSourceServiceProvider>();
 				platformView.UpdateBackgroundImageSourceAsync(image.ImageSource, provider)

src/Core/src/Handlers/View/ViewHandler.cs

@@ -386,7 +386,7 @@ public static void MapBackground(IViewHandler handler, IView view)
 			if (handler.PlatformView is not PlatformView platformView)
 				return;
 
-			if (view.Background is ImageSourcePaint image)
+			if (view.Background is IImageSourcePaint image)
 			{
 				var provider = handler.GetRequiredService<IImageSourceServiceProvider>();
 

src/Core/src/ImageSources/IImageSourcePaint.cs

@@ -0,0 +1,46 @@
+#nullable enable
+using Microsoft.Maui.Graphics;
+
+namespace Microsoft.Maui
+{
+	/// <summary>
+	/// Represents a <see cref="Paint"/> that fills an area with the contents of an <see cref="IImageSource"/>.
+	/// </summary>
+	/// <remarks>
+	/// <para>
+	/// Platform backends receive backgrounds as a <see cref="Paint"/> through <see cref="IView.Background"/>.
+	/// Pattern matching that paint against this interface is the supported way to detect an image-source
+	/// background and to obtain the <see cref="ImageSource"/> so it can be resolved with an
+	/// <see cref="IImageSourceServiceProvider"/>.
+	/// </para>
+	/// <para>
+	/// This interface is implemented by the paint that .NET MAUI produces for an image background, and it may
+	/// also be implemented by custom <see cref="Paint"/> types so that they are treated as image backgrounds by
+	/// the built-in handlers.
+	/// </para>
+	/// <example>
+	/// The following example shows how an out-of-tree handler can render an image background:
+	/// <code language="csharp"><![CDATA[
+	/// public static void MapBackground(IViewHandler handler, IView view)
+	/// {
+	///     if (view.Background is IImageSourcePaint imagePaint)
+	///     {
+	///         var provider = handler.GetRequiredService<IImageSourceServiceProvider>();
+	///         ApplyImageBackgroundAsync(handler.PlatformView, imagePaint.ImageSource, provider);
+	///     }
+	///     else
+	///     {
+	///         ApplyPaintBackground(handler.PlatformView, view.Background);
+	///     }
+	/// }
+	/// ]]></code>
+	/// </example>
+	/// </remarks>
+	public interface IImageSourcePaint
+	{
+		/// <summary>
+		/// Gets the image source that is used to fill the area.
+		/// </summary>
+		IImageSource? ImageSource { get; }
+	}
+}

src/Core/src/ImageSources/ImageSourcePaint.cs

@@ -3,7 +3,7 @@
 
 namespace Microsoft.Maui
 {
-	class ImageSourcePaint : Paint
+	class ImageSourcePaint : Paint, IImageSourcePaint
 	{
 		public ImageSourcePaint()
 		{

src/Core/src/Platform/Tizen/ViewExtensions.cs

@@ -60,7 +60,7 @@ public static void UpdateBackground(this ContentViewGroup platformView, IBorderV
 
 		public static void UpdateBackground(this NView platformView, IView view)
 		{
-			if (view.Background is ImageSourcePaint image)
+			if (view.Background is IImageSourcePaint image)
 			{
 				var provider = view.Handler?.GetRequiredService<IImageSourceServiceProvider>();
 				platformView.UpdateBackgroundImageSourceAsync(image.ImageSource, provider)

src/Core/src/Platform/iOS/PageExtensions.cs

@@ -14,7 +14,7 @@ public static void UpdateTitle(this UIViewController viewController, IContentVie
 
 		public static void UpdateBackground(this UIView platformView, IContentView page, IImageSourceServiceProvider? provider)
 		{
-			if (page.Background is ImageSourcePaint image)
+			if (page.Background is IImageSourcePaint image)
 				platformView.UpdateBackgroundImageSourceAsync(image.ImageSource, provider).FireAndForget();
 			else
 				platformView.UpdateBackground(page);

src/Core/src/PublicAPI/net-android/PublicAPI.Unshipped.txt

@@ -363,3 +363,5 @@ virtual Microsoft.Maui.Platform.StackNavigationManager.OnCreateNavigationAnimati
 Microsoft.Maui.ISwipeItemMenuItemIconColor
 Microsoft.Maui.ISwipeItemMenuItemIconColor.IconColor.get -> Microsoft.Maui.Graphics.Color?
 static Microsoft.Maui.Handlers.SwipeItemMenuItemHandler.MapIconColor(Microsoft.Maui.Handlers.ISwipeItemMenuItemHandler! handler, Microsoft.Maui.ISwipeItemMenuItem! view) -> void
+Microsoft.Maui.IImageSourcePaint
+Microsoft.Maui.IImageSourcePaint.ImageSource.get -> Microsoft.Maui.IImageSource?