Add public modal navigation extensibility seam for external backends

External platform backends (for example a community Tizen or GTK backend)
could not render modal push/pop without forking. `Window` constructed the
internal `ModalNavigationManager` directly, `NavigationImpl` routed
`PushModalAsync`/`PopModalAsync` through it, and the only way to supply
platform presentation was an internal partial class completion compiled
into `Microsoft.Maui.Controls` itself.

This adds a minimal, additive seam in `Microsoft.Maui.Controls.Platform`
that follows the existing `IAlertManager` and `IGesturePlatformManagerFactory`
extensibility patterns:

- `IModalNavigationPlatform` — presents and dismisses a single modal
  (`IsReady`, `PushModalAsync`, `PopModalAsync`, `PageAttached`, `Dispose`).
- `IModalNavigationPlatformFactory` — application-wide DI factory that
  creates one platform per `Window`. Returning `null` keeps the built-in
  implementation.
- `IModalNavigationHost` — the framework state a platform needs
  (`Window`, `MauiContext`, `PlatformModalStack`, `CurrentPage`,
  `CurrentPlatformPage`, `IsModalReady`, `IsBatchPopping`, `RequestSync`).

`ModalNavigationManager` now implements `IModalNavigationHost` and resolves
the factory lazily from the window handler's `IMauiContext.Services`, which
is the per-window service scope, so each window gets its own isolated
platform instance. The framework keeps ownership of the cross-platform modal
stack, page lifecycle events, `Window` modal events and the push/pop
reconciliation loop; only visual presentation is delegated.

When no factory is registered, behavior is unchanged: the existing
Android/iOS/MacCatalyst/Windows/Tizen/Standard partials are kept as the
fallback implementation and are only renamed to `*Core` so the shared file
can route between them and an override.

Adds unit tests covering DI selection, per-window isolation, push/pop
ordering, platform stack visibility during presentation, animation flag
propagation, deferred readiness via `RequestSync`, pop cancellation,
factory-returns-null fallback, push failure rollback, disposal on window
destroy and handler change, and the no-registration path; plus device tests
that exercise the seam with real handlers.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: Redth

src/Controls/src/Core/Platform/ModalNavigationManager/IModalNavigationHost.cs

@@ -0,0 +1,96 @@
+#nullable enable
+
+using System.Collections.Generic;
+
+namespace Microsoft.Maui.Controls.Platform
+{
+	/// <summary>
+	/// Exposes the cross-platform modal navigation state that a <see cref="IModalNavigationPlatform"/>
+	/// needs in order to present and dismiss modal pages.
+	/// </summary>
+	/// <remarks>
+	/// <para>
+	/// The framework implements this interface and supplies an instance to
+	/// <see cref="IModalNavigationPlatformFactory.CreateModalNavigationPlatform(IModalNavigationHost)"/>.
+	/// One host exists per <see cref="Controls.Window"/>, so an implementation must never be shared
+	/// between windows.
+	/// </para>
+	/// <para>
+	/// The framework owns the cross-platform modal stack, the page lifecycle events
+	/// (<c>Appearing</c>/<c>Disappearing</c>, <c>NavigatedTo</c>/<c>NavigatedFrom</c>), the
+	/// <see cref="Controls.Window.ModalPushing"/>/<see cref="Controls.Window.ModalPopped"/> events and the
+	/// reconciliation loop that keeps the platform stack in sync with the requested stack. A platform
+	/// implementation is only responsible for the visual presentation of a single push or pop.
+	/// </para>
+	/// </remarks>
+	public interface IModalNavigationHost
+	{
+		/// <summary>
+		/// Gets the window that owns this modal navigation host.
+		/// </summary>
+		Window Window { get; }
+
+		/// <summary>
+		/// Gets the <see cref="IMauiContext"/> scoped to <see cref="Window"/>.
+		/// </summary>
+		/// <exception cref="System.InvalidOperationException">
+		/// Thrown when the window does not currently have a handler and therefore has no context.
+		/// </exception>
+		IMauiContext MauiContext { get; }
+
+		/// <summary>
+		/// Gets the modal pages that the platform has actually presented, in push order.
+		/// The last entry is the modal currently on screen.
+		/// </summary>
+		/// <remarks>
+		/// This is maintained by the framework. It is updated before
+		/// <see cref="IModalNavigationPlatform.PushModalAsync(Page, bool)"/> is awaited and before
+		/// <see cref="IModalNavigationPlatform.PopModalAsync(Page, bool)"/> is awaited, so during those
+		/// calls it already reflects the requested end state.
+		/// </remarks>
+		IReadOnlyList<Page> PlatformModalStack { get; }
+
+		/// <summary>
+		/// Gets the page the user is expected to be looking at once the cross-platform modal stack is
+		/// fully applied. This is the topmost requested modal, or the window's page when no modal is
+		/// requested, with <see cref="Shell"/> unwrapped to its current page.
+		/// </summary>
+		Page? CurrentPage { get; }
+
+		/// <summary>
+		/// Gets the page that is currently hosting content on the platform: the topmost entry of
+		/// <see cref="PlatformModalStack"/>, or the window's page when no modal has been presented.
+		/// </summary>
+		/// <exception cref="System.InvalidOperationException">
+		/// Thrown when there is no presented modal and the window has no page.
+		/// </exception>
+		Page CurrentPlatformPage { get; }
+
+		/// <summary>
+		/// Gets a value indicating whether the framework considers the window ready to present modals
+		/// (the window and its page both have handlers, and <see cref="IModalNavigationPlatform.IsReady"/>
+		/// returned <see langword="true"/>).
+		/// </summary>
+		bool IsModalReady { get; }
+
+		/// <summary>
+		/// Gets a value indicating whether several modals are being dismissed as a single batch, for
+		/// example during a <see cref="Shell"/> pop-to-root. Implementations can use this to dismiss
+		/// without animation or intermediate layout so that the modals in between do not flash on screen.
+		/// </summary>
+		bool IsBatchPopping { get; }
+
+		/// <summary>
+		/// Asks the framework to re-run the reconciliation loop that compares the requested modal stack
+		/// with <see cref="PlatformModalStack"/> and issues any push or pop that is still outstanding.
+		/// </summary>
+		/// <remarks>
+		/// Call this when <see cref="IModalNavigationPlatform.IsReady"/> transitions from
+		/// <see langword="false"/> to <see langword="true"/>. The framework does not poll
+		/// <see cref="IModalNavigationPlatform.IsReady"/>, so a platform that defers readiness must
+		/// notify the framework through this method or queued modals will never be presented.
+		/// The call is safe to make from any thread and does not block.
+		/// </remarks>
+		void RequestSync();
+	}
+}

src/Controls/src/Core/Platform/ModalNavigationManager/IModalNavigationPlatform.cs

@@ -0,0 +1,90 @@
+#nullable enable
+
+using System;
+using System.Threading.Tasks;
+
+namespace Microsoft.Maui.Controls.Platform
+{
+	/// <summary>
+	/// Presents and dismisses modal pages for a single <see cref="Window"/>.
+	/// </summary>
+	/// <remarks>
+	/// <para>
+	/// Register an <see cref="IModalNavigationPlatformFactory"/> in the application's service collection
+	/// to supply an implementation. This is the extensibility point that lets an alternative platform
+	/// backend render modal navigation without forking the framework: the framework keeps ownership of
+	/// the cross-platform modal stack, page lifecycle events and the push/pop reconciliation loop, and
+	/// only the visual presentation is delegated here.
+	/// </para>
+	/// <para>
+	/// The framework creates one instance per window and disposes it when the window is destroyed or
+	/// when the window's handler changes. Implementations must therefore tolerate multiple
+	/// create/dispose cycles and must not be shared between windows.
+	/// </para>
+	/// <para>
+	/// All members are invoked on the UI thread.
+	/// </para>
+	/// </remarks>
+	public interface IModalNavigationPlatform : IDisposable
+	{
+		/// <summary>
+		/// Gets a value indicating whether the backend can present or dismiss a modal right now.
+		/// </summary>
+		/// <remarks>
+		/// While this returns <see langword="false"/> the framework still records pushes and pops on the
+		/// cross-platform modal stack and still raises the corresponding page lifecycle events, but it
+		/// does not call <see cref="PushModalAsync(Page, bool)"/> or <see cref="PopModalAsync(Page, bool)"/>.
+		/// When the backend becomes ready it must call
+		/// <see cref="IModalNavigationHost.RequestSync"/> so the queued operations are applied.
+		/// Return <see langword="true"/> unconditionally if the backend has no readiness requirement.
+		/// </remarks>
+		bool IsReady { get; }
+
+		/// <summary>
+		/// Presents <paramref name="modal"/> on top of
+		/// <see cref="IModalNavigationHost.CurrentPlatformPage"/>.
+		/// </summary>
+		/// <param name="modal">The page to present. It has already been added to
+		/// <see cref="IModalNavigationHost.PlatformModalStack"/> when this method is called.</param>
+		/// <param name="animated"><see langword="true"/> to animate the transition.</param>
+		/// <returns>
+		/// A task that completes once the modal is on screen and safe to dismiss. The framework awaits
+		/// this task before applying any further modal operation, so completing early can allow a
+		/// subsequent pop to race the presentation.
+		/// </returns>
+		/// <remarks>
+		/// If this task faults, the framework removes <paramref name="modal"/> from
+		/// <see cref="IModalNavigationHost.PlatformModalStack"/> again and rethrows to the caller of
+		/// <c>PushModalAsync</c>.
+		/// </remarks>
+		Task PushModalAsync(Page modal, bool animated);
+
+		/// <summary>
+		/// Dismisses <paramref name="modal"/>, revealing
+		/// <see cref="IModalNavigationHost.CurrentPlatformPage"/>.
+		/// </summary>
+		/// <param name="modal">The page to dismiss. It has already been removed from
+		/// <see cref="IModalNavigationHost.PlatformModalStack"/> when this method is called, so
+		/// <see cref="IModalNavigationHost.CurrentPlatformPage"/> already refers to the page that is
+		/// about to be revealed.</param>
+		/// <param name="animated"><see langword="true"/> to animate the transition. The framework passes
+		/// the value that was supplied to the matching push when the pop is the result of stack
+		/// reconciliation, and the value supplied to <c>PopModalAsync</c> otherwise.</param>
+		/// <returns>A task that completes once the modal is off screen.</returns>
+		/// <remarks>
+		/// Implementations are responsible for releasing the platform views created for
+		/// <paramref name="modal"/>. The framework detaches the page from its parent after this task
+		/// completes.
+		/// </remarks>
+		Task PopModalAsync(Page modal, bool animated);
+
+		/// <summary>
+		/// Called when the window's page gets a handler, including when the page is replaced.
+		/// </summary>
+		/// <remarks>
+		/// Use this to attach platform hooks that depend on the window's content being realized, such as
+		/// a hardware back button handler. This may be called multiple times for the same window.
+		/// </remarks>
+		void PageAttached();
+	}
+}

src/Controls/src/Core/Platform/ModalNavigationManager/IModalNavigationPlatformFactory.cs

@@ -0,0 +1,86 @@
+#nullable enable
+
+namespace Microsoft.Maui.Controls.Platform
+{
+	/// <summary>
+	/// Application-wide factory for creating <see cref="IModalNavigationPlatform"/> instances.
+	/// Register an implementation in the application's
+	/// <see cref="Microsoft.Extensions.DependencyInjection.IServiceCollection"/> to replace the built-in
+	/// modal presentation for every window.
+	/// </summary>
+	/// <remarks>
+	/// <para>
+	/// When an <see cref="IModalNavigationPlatformFactory"/> is present in
+	/// <see cref="IMauiContext.Services"/> for a window, the framework calls
+	/// <see cref="CreateModalNavigationPlatform(IModalNavigationHost)"/> once for that window and routes
+	/// every modal push and pop to the returned instance instead of the built-in platform code. This
+	/// lets alternative platform backends render modal navigation without reflection, partial classes or
+	/// forking, while the framework keeps ownership of the cross-platform modal stack, the page
+	/// lifecycle events and the push/pop reconciliation loop.
+	/// </para>
+	/// <para>
+	/// The factory itself is resolved from the window's service scope, so it may be registered with any
+	/// lifetime. The framework always calls it once per window and disposes the returned instance, so
+	/// return a new <see cref="IModalNavigationPlatform"/> for each call.
+	/// </para>
+	/// <example>
+	/// Registering a backend that presents modals with its own native window stack:
+	/// <code lang="csharp">
+	/// public sealed class MyModalNavigationPlatformFactory : IModalNavigationPlatformFactory
+	/// {
+	///     public IModalNavigationPlatform? CreateModalNavigationPlatform(IModalNavigationHost host)
+	///         =&gt; new MyModalNavigationPlatform(host);
+	/// }
+	///
+	/// public sealed class MyModalNavigationPlatform : IModalNavigationPlatform
+	/// {
+	///     readonly IModalNavigationHost _host;
+	///
+	///     public MyModalNavigationPlatform(IModalNavigationHost host) =&gt; _host = host;
+	///
+	///     public bool IsReady =&gt; true;
+	///
+	///     public async Task PushModalAsync(Page modal, bool animated)
+	///     {
+	///         var nativeView = modal.ToPlatform(_host.MauiContext);
+	///         await MyNativeModalStack.For(_host.Window).PushAsync(nativeView, animated);
+	///     }
+	///
+	///     public async Task PopModalAsync(Page modal, bool animated)
+	///     {
+	///         await MyNativeModalStack.For(_host.Window).PopAsync(animated &amp;&amp; !_host.IsBatchPopping);
+	///         (modal.Handler as IPlatformViewHandler)?.Dispose();
+	///     }
+	///
+	///     public void PageAttached()
+	///     {
+	///         MyNativeWindow.For(_host.Window).BackButtonPressed =
+	///             () =&gt; _host.CurrentPage?.SendBackButtonPressed() ?? false;
+	///     }
+	///
+	///     public void Dispose() =&gt; MyNativeModalStack.Release(_host.Window);
+	/// }
+	///
+	/// // In MauiProgram:
+	/// builder.Services.AddSingleton&lt;IModalNavigationPlatformFactory, MyModalNavigationPlatformFactory&gt;();
+	/// </code>
+	/// </example>
+	/// </remarks>
+	public interface IModalNavigationPlatformFactory
+	{
+		/// <summary>
+		/// Creates the <see cref="IModalNavigationPlatform"/> for a window.
+		/// </summary>
+		/// <param name="host">
+		/// The per-window host that exposes the framework's modal navigation state. Keep a reference to
+		/// it; it stays valid for the lifetime of the returned instance.
+		/// </param>
+		/// <returns>
+		/// A new <see cref="IModalNavigationPlatform"/> owned and disposed by the framework, or
+		/// <see langword="null"/> to let the window keep the built-in platform implementation. Returning
+		/// <see langword="null"/> is useful when a backend only wants to override modal navigation for
+		/// certain windows.
+		/// </returns>
+		IModalNavigationPlatform? CreateModalNavigationPlatform(IModalNavigationHost host);
+	}
+}

src/Controls/src/Core/Platform/ModalNavigationManager/ModalNavigationManager.Android.cs

@@ -92,7 +92,7 @@ ViewGroup GetModalParentView()
 				throw new InvalidOperationException("Root View Needs to be set");
 		}
 
-		Task<Page> PopModalPlatformAsync(bool animated)
+		Task<Page> PopModalPlatformCoreAsync(bool animated)
 		{
 			Page modal = CurrentPlatformModalPage;
 			_platformModalPages.Remove(modal);
@@ -161,7 +161,7 @@ AView GetCurrentRootView()
 					throw new InvalidOperationException("Current Root View cannot be null");
 		}
 
-		async Task PushModalPlatformAsync(Page modal, bool animated)
+		async Task PushModalPlatformCoreAsync(Page modal, bool animated)
 		{
 			var viewToHide = GetCurrentRootView();
 

src/Controls/src/Core/Platform/ModalNavigationManager/ModalNavigationManager.Standard.cs

@@ -8,22 +8,22 @@ namespace Microsoft.Maui.Controls.Platform
 {
 	internal partial class ModalNavigationManager
 	{
-		Task<Page> PopModalPlatformAsync(bool animated)
+		Task<Page> PopModalPlatformCoreAsync(bool animated)
 		{
 			var currentPage = CurrentPlatformPage!;
 			_platformModalPages.Remove(currentPage);
 			return Task.FromResult(currentPage);
 		}
 
-		Task PushModalPlatformAsync(Page modal, bool animated)
+		Task PushModalPlatformCoreAsync(Page modal, bool animated)
 		{
 			_platformModalPages.Add(modal);
 			return Task.CompletedTask;
 		}
 
-		Task SyncModalStackWhenPlatformIsReadyAsync() =>
+		Task SyncModalStackWhenPlatformIsReadyCoreAsync() =>
 			SyncPlatformModalStackAsync();
 
-		bool IsModalPlatformReady => true;
+		bool IsModalPlatformReadyCore => true;
 	}
 }

src/Controls/src/Core/Platform/ModalNavigationManager/ModalNavigationManager.Tizen.cs

@@ -10,17 +10,17 @@ internal partial class ModalNavigationManager
 		NavigationStack _modalStack => WindowMauiContext.GetModalStack();
 		IPageController CurrentPageController => CurrentPage!;
 
-		Task SyncModalStackWhenPlatformIsReadyAsync() =>
+		Task SyncModalStackWhenPlatformIsReadyCoreAsync() =>
 			SyncPlatformModalStackAsync();
 
-		bool IsModalPlatformReady => true;
+		bool IsModalPlatformReadyCore => true;
 
 		partial void OnPageAttachedHandler()
 		{
 			WindowMauiContext.GetPlatformWindow().SetBackButtonPressedHandler(OnBackButtonPressed);
 		}
 
-		async Task<Page> PopModalPlatformAsync(bool animated)
+		async Task<Page> PopModalPlatformCoreAsync(bool animated)
 		{
 			Page modal = CurrentPlatformModalPage;
 			_platformModalPages.Remove(modal);
@@ -37,7 +37,7 @@ async Task<Page> PopModalPlatformAsync(bool animated)
 			return modal;
 		}
 
-		async Task PushModalPlatformAsync(Page modal, bool animated)
+		async Task PushModalPlatformCoreAsync(Page modal, bool animated)
 		{
 			CurrentPageController?.SendDisappearing();
 			_platformModalPages.Add(modal);

src/Controls/src/Core/Platform/ModalNavigationManager/ModalNavigationManager.Windows.cs

@@ -29,7 +29,7 @@ void OnWindowActivated(object? sender, EventArgs e)
 			}
 		}
 
-		Task<Page> PopModalPlatformAsync(bool animated)
+		Task<Page> PopModalPlatformCoreAsync(bool animated)
 		{
 			var tcs = new TaskCompletionSource<Page>();
 			var poppedPage = CurrentPlatformModalPage;
@@ -38,7 +38,7 @@ Task<Page> PopModalPlatformAsync(bool animated)
 			return tcs.Task;
 		}
 
-		Task PushModalPlatformAsync(Page modal, bool animated)
+		Task PushModalPlatformCoreAsync(Page modal, bool animated)
 		{
 			_ = modal ?? throw new ArgumentNullException(nameof(modal));