Shaunebu.MAUI.Navigation.CodeFixes 1.0.0-preview.1

Shaunebu.MAUI.Navigation

A commercial-grade, type-safe navigation platform for .NET MAUI.
Built around structured results, guard pipelines, named flows, overlay management, compile-time code generation, and a fully integrated Visual Studio debugger extension.

Table of Contents

• Overview
• Key Features
• Architecture Overview
• NuGet Packages
• VSIX Extension
• Quick Start
• Installation
• Documentation Sections
• API Reference

Overview

Shaunebu.MAUI.Navigation replaces the fragmented MAUI/Shell navigation surface — Shell.Current.GoToAsync, NavigationPage.PushAsync, Application.Current.MainPage.Navigation — with a single, testable, observable abstraction: INavigationHandler.

Every navigation call passes through a deterministic 10-step pipeline:

1. Create NavigationOperation
2. Validate the target page or route
3. Check duplicate-navigation threshold
4. Acquire the navigation lock
5. Run all registered INavigationGuard implementations
6. Resolve the route via INavigationRouteRegistry
7. Resolve the page via IPageResolver
8. Execute the appropriate adapter (Shell or NavigationPage)
9. Invoke INavigationAware lifecycle callbacks on the ViewModel
10. Emit INavigationDiagnostics events and return NavigationResult

All failures are returned as structured NavigationResult values — never silent exceptions in production.

Key Features

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         Your Application                            │
│  ViewModels inject INavigationHandler / INavigationFlowManager      │
└────────────────────────────┬────────────────────────────────────────┘
							 │
┌────────────────────────────▼────────────────────────────────────────┐
│                    Navigation Pipeline                              │
│  Duplicate check → Lock → Guards → Route resolution → Adapter      │
│  → INavigationAware callbacks → INavigationDiagnostics → Result     │
└────────┬──────────────┬──────────────┬───────────────┬─────────────┘
		 │              │              │               │
   Shell Adapter  NavigationPage  Overlay System   Flow Manager
		 │              │              │               │
┌────────▼──────────────▼──────────────▼───────────────▼─────────────┐
│                  MAUI Platform Layer                                │
│       Shell.Current / NavigationPage / Application.Current         │
└─────────────────────────────────────────────────────────────────────┘
		 │
┌────────▼─────────────────────────────────────────────────────────────┐
│                  Diagnostics + Debugger (DEBUG only)                 │
│   NavigationDiagnosticsBus → SessionRecorder → WarningEngine        │
│   → StackDiffEngine → Exporter → VSIX Tool Window                  │
└─────────────────────────────────────────────────────────────────────┘

NuGet Packages

Install the core package and generators in your MAUI app project. Add Analyzers + CodeFixes for compile-time enforcement. Add Debugger only in DEBUG configurations.

VSIX Extension

The Navigation Inspector Visual Studio extension provides:

• Live stack viewer — real-time navigation and modal stack while debugging
• Timeline panel — chronological view of all navigation operations in a session
• Warning viewer — runtime warnings surfaced from NavigationRuntimeWarningEngine
• Frame inspector — per-operation detail (route, parameters, timing, stack diff)
• Session loader — open exported .json session files for post-mortem analysis

Install from the Visual Studio Marketplace or the vsix/ build output.

Quick Start

1. Register Navigation

// MauiProgram.cs
builder.UseShaunebuNavigation(options =>
{
	options.DefaultNavigationMode      = NavigationPresentationMode.Shell;
	options.PreventDoubleNavigation    = true;
	options.DoubleNavigationThreshold  = TimeSpan.FromMilliseconds(750);
	options.EnableDiagnostics          = true;
	options.EnableNavigationGuards     = true;
	options.EnableOverlaySystem        = true;
	options.ThrowOnNavigationFailure   = false;

	// Route registration via source generator
	GeneratedNavigationRegistration.RegisterGeneratedRoutes(options);
});

2. Annotate Pages

[NavigationRoute("main/home", Flow = "Main")]
public partial class HomePage : ContentPage { }

[NavigationRoute("auth/login", Flow = "Auth")]
public partial class LoginPage : ContentPage { }

3. Navigate in ViewModels

public sealed class LoginViewModel
{
	private readonly INavigationHandler _navigation;
	private readonly INavigationFlowManager _flowManager;

	public LoginViewModel(INavigationHandler navigation, INavigationFlowManager flowManager)
	{
		_navigation  = navigation;
		_flowManager = flowManager;
	}

	public async Task LoginAsync()
	{
		// Perform login …

		var result = await _flowManager.ResetToFlowAsync<MainFlow>();
		if (!result.Succeeded)
			await ShowErrorAsync(result.Message);
	}
}

4. Handle Results

var result = await _navigation.GoToAsync<SettingsPage>();

if (!result.Succeeded)
{
	switch (result.FailureReason)
	{
		case NavigationFailureReason.GuardRejected:
			await ShowAlertAsync("Access denied.");
			break;
		case NavigationFailureReason.DuplicateNavigationPrevented:
			break; // user tapped twice — safe to ignore
		default:
			_logger.LogWarning("Navigation failed: {Reason}", result.FailureReason);
			break;
	}
}

Documentation Sections

API Reference

See reference/api-reference.md for the complete index of all public interfaces, classes, records, enums, and extension methods.