Scope IImageSourcePaint to consumption-only

Addresses review feedback that the original change over-promised support
for third-party implementations of the new interface.

The public read contract is unchanged and still solves the blocker: an
external backend can pattern match `IView.Background` and read the image
source with no reflection and no internals access.

What changed:

- Document the interface as consumption-only. Implementing it outside of
  .NET MAUI is explicitly unsupported, and .NET MAUI reserves the right to
  add members in future releases.
- Revert the in-tree pattern matches back to the internal `ImageSourcePaint`.
  Custom paints were never reliably honored: specialized handlers such as
  `LayoutHandler.MapBackground` call `UpdateBackground` directly and bypass
  the image-source path, and `Brush`'s paint-to-brush conversion only
  round-trips an `IImageSource` that is a Controls `ImageSource`. Matching
  the concrete type keeps behavior provably identical to before, making this
  change purely additive.
- Drop the tests asserting that externally-authored paints implementing the
  interface are supported. The remaining tests prove a fake external backend
  can pattern match and read MAUI's built-in internal image paint through
  public API only, without implementing the interface itself.
- Document that values arise as a `Paint` from `IView.Background`, that a
  null `ImageSource` means an image background with nothing to draw, and how
  this differs from `Microsoft.Maui.Graphics.ImagePaint`, which carries an
  already-loaded `IImage`. Both are covered by new tests.

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 IImageSourcePaint imageSourcePaint && imageSourcePaint.ImageSource is ImageSource imageSource)
+			if (paint is ImageSourcePaint imageSourcePaint && imageSourcePaint.ImageSource is ImageSource imageSource)
 				return new ImageBrush { ImageSource = imageSource };
 
 			return null;

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

@@ -28,30 +28,12 @@ public void ImageSourcePaintConvertsBackToImageBrush()
 			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 IImageSourcePaint image)
+			if (editor.Background is ImageSourcePaint 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 IImageSourcePaint image)
+			if (entry.Background is ImageSourcePaint 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 IImageSourcePaint image)
+			if (view.Background is ImageSourcePaint image)
 			{
 				var provider = handler.GetRequiredService<IImageSourceServiceProvider>();
 

src/Core/src/ImageSources/IImageSourcePaint.cs

@@ -4,27 +4,49 @@
 namespace Microsoft.Maui
 {
 	/// <summary>
-	/// Represents a <see cref="Paint"/> that fills an area with the contents of an <see cref="IImageSource"/>.
+	/// Exposes the <see cref="IImageSource"/> of a <see cref="Paint"/> that .NET MAUI uses to fill an area
+	/// with an image.
 	/// </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"/>.
+	/// This is a <b>consumption-only</b> contract. It exists so that code receiving a <see cref="Paint"/> -
+	/// most commonly a platform backend handling <see cref="IView.Background"/> - can recognize an image
+	/// background and read its image source without reflection.
 	/// </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.
+	/// <b>Implementing this interface outside of .NET MAUI is not supported.</b> .NET MAUI reserves the right
+	/// to add members to this interface in future releases, which would be a breaking change for external
+	/// implementers. Only paints created by .NET MAUI are guaranteed to be recognized and rendered by the
+	/// built-in handlers; a custom <see cref="Paint"/> implementing this interface is not guaranteed to be
+	/// honored, because not every built-in handler routes backgrounds through the image-source path.
+	/// </para>
+	/// <para>
+	/// Values implementing this interface are obtained by pattern matching an existing <see cref="Paint"/>,
+	/// typically from <see cref="IView.Background"/>. In .NET MAUI a paint of this kind is produced when a
+	/// background is set from an image - for example a <c>Microsoft.Maui.Controls.ImageBrush</c>, or
+	/// <c>Page.BackgroundImageSource</c>.
+	/// </para>
+	/// <para>
+	/// <see cref="ImageSource"/> can be <see langword="null"/>, which represents an image background with
+	/// nothing to draw. Treat it the same as having no image background: clear any previously applied image
+	/// rather than attempting to resolve it. A non-<see langword="null"/> value should be resolved through an
+	/// <see cref="IImageSourceServiceProvider"/>; note that resolution is asynchronous and may still yield no
+	/// image.
+	/// </para>
+	/// <para>
+	/// This is distinct from <see cref="ImagePaint"/>. <see cref="ImagePaint"/> carries an already-loaded
+	/// <see cref="IImage"/> for drawing operations, whereas this contract carries an unresolved
+	/// <see cref="IImageSource"/> that describes where an image comes from (a file, URI, stream, or font glyph)
+	/// and must be loaded through an image source service. A paint will not implement both.
 	/// </para>
 	/// <example>
-	/// The following example shows how an out-of-tree handler can render an image background:
+	/// The following example shows how a platform backend can render an image background:
 	/// <code language="csharp"><![CDATA[
 	/// public static void MapBackground(IViewHandler handler, IView view)
 	/// {
 	///     if (view.Background is IImageSourcePaint imagePaint)
 	///     {
+	///         // May be null, in which case any existing image background is cleared.
 	///         var provider = handler.GetRequiredService<IImageSourceServiceProvider>();
 	///         ApplyImageBackgroundAsync(handler.PlatformView, imagePaint.ImageSource, provider);
 	///     }
@@ -39,7 +61,7 @@ namespace Microsoft.Maui
 	public interface IImageSourcePaint
 	{
 		/// <summary>
-		/// Gets the image source that is used to fill the area.
+		/// Gets the image source used to fill the area, or <see langword="null"/> when there is no image to draw.
 		/// </summary>
 		IImageSource? ImageSource { get; }
 	}

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 IImageSourcePaint image)
+			if (view.Background is ImageSourcePaint 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 IImageSourcePaint image)
+			if (page.Background is ImageSourcePaint image)
 				platformView.UpdateBackgroundImageSourceAsync(image.ImageSource, provider).FireAndForget();
 			else
 				platformView.UpdateBackground(page);

src/Core/tests/UnitTests/ImageSource/ImageSourcePaintContractTests.cs

@@ -8,7 +8,8 @@ namespace Microsoft.Maui.UnitTests.ImageSource
 {
 	/// <summary>
 	/// Verifies the public <see cref="IImageSourcePaint"/> contract that out-of-tree platform backends
-	/// rely on to detect and render image-source backgrounds.
+	/// consume to detect and read image-source backgrounds. The contract is consumption-only, so these
+	/// tests never implement it outside of .NET MAUI.
 	/// </summary>
 	[Category(TestCategory.Core)]
 	public class ImageSourcePaintContractTests
@@ -60,18 +61,6 @@ public void ExternalBackendCanReadImageSourceFromBuiltInPaint()
 			Assert.Same(imageSource, result.ImageSource);
 		}
 
-		[Fact]
-		public void ExternalBackendCanReadImageSourceFromExternalPaint()
-		{
-			var imageSource = new ExternalImageSource();
-			var view = new ViewStub { Background = new ExternalImageSourcePaint(imageSource) };
-
-			var result = FakeExternalBackend.Describe(view);
-
-			Assert.Equal(FakeExternalBackend.PaintKind.Image, result.Kind);
-			Assert.Same(imageSource, result.ImageSource);
-		}
-
 		[Fact]
 		public void ExternalBackendDistinguishesSolidPaint()
 		{
@@ -105,25 +94,34 @@ public void ExternalBackendDistinguishesNoPaint()
 			Assert.Null(result.ImageSource);
 		}
 
-		/// <summary>
-		/// A paint authored entirely outside of .NET MAUI. It only depends on public API, which proves a
-		/// third-party backend can both produce and consume image-source backgrounds.
-		/// </summary>
-		class ExternalImageSourcePaint : Paint, IImageSourcePaint
+		[Fact]
+		public void ExternalBackendReadsNullImageSourceAsAnImagePaint()
 		{
-			public ExternalImageSourcePaint(IImageSource imageSource) => ImageSource = imageSource;
+			// A null ImageSource still identifies an image background; it simply has nothing to draw.
+			var view = new ViewStub { Background = new ImageSourcePaint() };
 
-			public IImageSource ImageSource { get; }
+			var result = FakeExternalBackend.Describe(view);
+
+			Assert.Equal(FakeExternalBackend.PaintKind.Image, result.Kind);
+			Assert.Null(result.ImageSource);
 		}
 
-		class ExternalImageSource : IImageSource
+		[Fact]
+		public void ImagePaintIsNotAnImageSourcePaint()
 		{
-			public bool IsEmpty => false;
+			// Graphics.ImagePaint carries an already-loaded IImage and is a distinct concept.
+			var view = new ViewStub { Background = new ImagePaint() };
+
+			var result = FakeExternalBackend.Describe(view);
+
+			Assert.NotEqual(FakeExternalBackend.PaintKind.Image, result.Kind);
+			Assert.IsNotAssignableFrom<IImageSourcePaint>(view.Background);
 		}
 
 		/// <summary>
-		/// Stands in for an out-of-tree platform backend. Every member it touches is public .NET MAUI API and
-		/// the image source is retrieved through the contract - no reflection and no internals access.
+		/// Stands in for an out-of-tree platform backend. It only consumes the contract - it never implements
+		/// it - and every member it touches is public .NET MAUI API, so the image source is retrieved with no
+		/// reflection and no internals access.
 		/// </summary>
 		static class FakeExternalBackend
 		{