Refactor migration guide for Terminal.Gui v2

Restructured and expanded the migration guide to provide a comprehensive resource for transitioning from Terminal.Gui v1 to v2. Key updates include:

- Added a Table of Contents for easier navigation.
- Summarized major architectural changes in v2, including the instance-based application model, IRunnable architecture, and 24-bit TrueColor support.
- Updated examples to reflect new patterns, such as initializers replacing constructors and explicit disposal using `IDisposable`.
- Documented changes to the layout system, including the removal of `Absolute`/`Computed` styles and the introduction of `Viewport`.
- Standardized event patterns to use `object sender, EventArgs args`.
- Detailed updates to the Keyboard, Mouse, and Navigation APIs, including configurable key bindings and viewport-relative mouse coordinates.
- Replaced legacy components like `ScrollView` and `ContextMenu` with built-in scrolling and `PopoverMenu`.
- Clarified disposal rules and introduced best practices for resource management.
- Provided a complete migration example and a summary of breaking changes.

This update aims to simplify the migration process by addressing breaking changes, introducing new features, and aligning with modern .NET conventions.

docfx/docs/migratingfromv1.md

@@ -1,499 +1,1114 @@
 # Migrating From v1 To v2
 
-This document provides an overview of the changes between Terminal.Gui v1 and v2. It is intended to help developers migrate their applications from v1 to v2.
+This document provides a comprehensive guide for migrating applications from Terminal.Gui v1 to v2. 
 
-For detailed breaking change documentation check out this Discussion: https://github.com/gui-cs/Terminal.Gui/discussions/2448
+For detailed breaking change documentation, check out this Discussion: https://github.com/gui-cs/Terminal.Gui/discussions/2448
 
-## View Constructors -> Initializers
+## Table of Contents
 
-In v1, @Terminal.Gui.View and most sub-classes had multiple constructors that took a variety of parameters. In v2, the constructors have been replaced with initializers. This change was made to simplify the API and make it easier to use. In addition, the v1 constructors drove a false (and needlessly complex) distinction between "Absolute" and "Computed" layout. In v2, the layout system is much simpler and more intuitive.
+- [Overview of Major Changes](#overview-of-major-changes)
+- [Application Architecture](#application-architecture)
+- [View Construction and Initialization](#view-construction-and-initialization)
+- [Layout System Changes](#layout-system-changes)
+- [Color and Attribute Changes](#color-and-attribute-changes)
+- [Type Changes](#type-changes)
+- [Unicode and Text](#unicode-and-text)
+- [Keyboard API](#keyboard-api)
+- [Mouse API](#mouse-api)
+- [Navigation Changes](#navigation-changes)
+- [Scrolling Changes](#scrolling-changes)
+- [Adornments](#adornments)
+- [Event Pattern Changes](#event-pattern-changes)
+- [View-Specific Changes](#view-specific-changes)
+- [Disposal and Resource Management](#disposal-and-resource-management)
+- [API Terminology Changes](#api-terminology-changes)
 
-### How to Fix
+---
 
-Replace the constructor calls with initializer calls.
+## Overview of Major Changes
 
-```diff
-- var myView = new View (new Rect (10, 10, 40, 10));
-+ var myView = new View { X = 10, Y = 10, Width = 40, Height = 10 };
+Terminal.Gui v2 represents a major architectural evolution with these key improvements:
+
+1. **Instance-Based Application Model** - Move from static `Application` to `IApplication` instances
+2. **IRunnable Architecture** - Interface-based runnable pattern with type-safe results
+3. **Simplified Layout** - Removed Absolute/Computed distinction, improved adornments
+4. **24-bit TrueColor** - Full color support by default
+5. **Enhanced Input** - Better keyboard and mouse APIs
+6. **Built-in Scrolling** - All views support scrolling inherently
+7. **Fluent API** - Method chaining for elegant code
+8. **Proper Disposal** - IDisposable pattern throughout
+
+---
+
+## Application Architecture
+
+### Instance-Based Application Model
+
+**v1 Pattern (Static):**
+```csharp
+// v1 - static Application
+Application.Init();
+var top = Application.Top;
+top.Add(myView);
+Application.Run();
+Application.Shutdown();
 ```
 
-## TrueColor Support - 24-bit Color is the default
+**v2 Recommended Pattern (Instance-Based):**
+```csharp
+// v2 - instance-based with using statement
+using (var app = Application.Create().Init())
+{
+    var top = new Window();
+    top.Add(myView);
+    app.Run(top);
+    top.Dispose();
+} // app.Dispose() called automatically
+```
 
-Terminal.Gui v2 now supports 24-bit color by default. This means that the colors you use in your application will be more accurate and vibrant. If you are using custom colors in your application, you may need to update them to use the new 24-bit color format.
+**v2 Legacy Pattern (Still Works):**
+```csharp
+// v2 - legacy static (marked obsolete but functional)
+Application.Init();
+var top = new Window();
+top.Add(myView);
+Application.Run(top);
+top.Dispose();
+Application.Shutdown(); // Obsolete - use Dispose() instead
+```
 
-The @Terminal.Gui.Attribute class has been simplified. Color names now match the ANSI standard ('Brown' is now called 'Yellow')
+### IRunnable Architecture
 
-### How to Fix
+v2 introduces `IRunnable<TResult>` for type-safe, runnable views:
 
-Static class `Attribute.Make` has been removed. Use constructor instead
+```csharp
+// Create a dialog that returns a typed result
+public class FileDialog : Runnable<string?>
+{
+    private TextField _pathField;
+    
+    public FileDialog()
+    {
+        Title = "Select File";
+        _pathField = new TextField { Width = Dim.Fill() };
+        Add(_pathField);
+        
+        var okButton = new Button { Text = "OK", IsDefault = true };
+        okButton.Accepting += (s, e) => {
+            Result = _pathField.Text;
+            Application.RequestStop();
+        };
+        AddButton(okButton);
+    }
+    
+    protected override bool OnIsRunningChanging(bool oldValue, bool newValue)
+    {
+        if (!newValue)  // Stopping - extract result before disposal
+        {
+            Result = _pathField?.Text;
+        }
+        return base.OnIsRunningChanging(oldValue, newValue);
+    }
+}
 
-```diff
-- var c = Attribute.Make(Color.BrightMagenta, Color.Blue);
-+ var c = new Attribute(Color.BrightMagenta, Color.Blue);
+// Use with fluent API
+using (var app = Application.Create().Init())
+{
+    app.Run<FileDialog>();
+    string? result = app.GetResult<string>();
+    
+    if (result is { })
+    {
+        OpenFile(result);
+    }
+}
 ```
 
-```diff
-- var c = Color.Brown;
-+ var c = Color.Yellow;
+**Key Benefits:**
+- Type-safe results (no casting)
+- Automatic disposal of framework-created runnables
+- CWP-compliant lifecycle events
+- Works with any View (not just Toplevel)
+
+### Disposal and Resource Management
+
+v2 requires explicit disposal:
+
+```csharp
+// ❌ v1 - Application.Shutdown() disposed everything
+Application.Init();
+var top = new Window();
+Application.Run(top);
+Application.Shutdown(); // Disposed top automatically
+
+// ✅ v2 - Dispose views explicitly
+using (var app = Application.Create().Init())
+{
+    var top = new Window();
+    app.Run(top);
+    top.Dispose(); // Must dispose
+}
+
+// ✅ v2 - Framework-created runnables disposed automatically
+using (var app = Application.Create().Init())
+{
+    app.Run<MyDialog>(); // Dialog disposed automatically
+    var result = app.GetResult<MyResult>();
+}
 ```
 
-## Low-Level Type Changes
+**Disposal Rules:**
+- "Whoever creates it, owns it"
+- `Run<TRunnable>()`: Framework creates → Framework disposes
+- `Run(IRunnable)`: Caller creates → Caller disposes
+- Always dispose `IApplication` (use `using` statement)
 
-* `Rect` -> `Rectangle`
-* `Point` -> `Point`
-* `Size` -> `Size`
+### View.App Property
 
-### How to Fix
+Views now have an `App` property for accessing the application context:
 
-* Replace `Rect` with `Rectangle`
+```csharp
+// ❌ v1 - Direct static reference
+Application.Driver.Move(x, y);
+
+// ✅ v2 - Use View.App
+App?.Driver.Move(x, y);
+
+// ✅ v2 - Dependency injection
+public class MyView : View
+{
+    private readonly IApplication _app;
+    
+    public MyView(IApplication app)
+    {
+        _app = app;
+    }
+}
+```
 
+---
 
-## `NStack.string` has been removed. Use `System.Rune` instead. 
+## View Construction and Initialization
 
-See [Unicode](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#unicode) for details.
+### Constructors → Initializers
+
+**v1:**
+```csharp
+var myView = new View(new Rect(10, 10, 40, 10));
+```
+
+**v2:**
+```csharp
+var myView = new View 
+{ 
+    X = 10, 
+    Y = 10, 
+    Width = 40, 
+    Height = 10 
+};
+```
 
-### How to Fix
+### Initialization Pattern
 
-Replace `using` statements with the `System.Text` namespace
+v2 uses `ISupportInitializeNotification`:
 
-```diff
-- using NStack;
-+ using System.Text;
+```csharp
+// v1 - No explicit initialization
+var view = new View();
+Application.Run(view);
+
+// v2 - Automatic initialization via BeginInit/EndInit
+var view = new View();
+// BeginInit() called automatically when added to SuperView
+// EndInit() called automatically
+// Initialized event raised after EndInit()
 ```
 
-Anywhere you have an implicit cast from `char` to `Rune`, replace with a constructor call 
+---
+
+## Layout System Changes
+
+### Removed LayoutStyle Distinction
 
-```diff
-- myView.AddRune(col, row, '▄');
-+ myView.AddRune(col, row, new Rune('▄'));
+v1 had `Absolute` and `Computed` layout styles. v2 removed this distinction.
+
+**v1:**
+```csharp
+view.LayoutStyle = LayoutStyle.Computed;
+```
+
+**v2:**
+```csharp
+// No LayoutStyle - all layout is declarative via Pos/Dim
+view.X = Pos.Center();
+view.Y = Pos.Center();
+view.Width = Dim.Percent(50);
+view.Height = Dim.Fill();
 ```
 
-When measuring the screen space taken up by a `Rune` use `GetColumns()`
+### Frame vs Bounds
+
+**v1:**
+- `Frame` - Position/size in SuperView coordinates
+- `Bounds` - Always `{0, 0, Width, Height}` (location always empty)
 
-```diff
-- Rune.ColumnWidth(rune);
-+ rune.GetColumns();
+**v2:**
+- `Frame` - Position/size in SuperView coordinates (same as v1)
+- `Viewport` - Visible area in content coordinates (replaces Bounds)
+  - **Important**: `Viewport.Location` can now be non-zero for scrolling
+
+```csharp
+// ❌ v1
+var size = view.Bounds.Size;
+Debug.Assert(view.Bounds.Location == Point.Empty); // Always true
+
+// ✅ v2
+var visibleArea = view.Viewport;
+var contentSize = view.GetContentSize();
+
+// Viewport.Location can be non-zero when scrolled
+view.ScrollVertical(10);
+Debug.Assert(view.Viewport.Location.Y == 10);
 ```
-When measuring the screen space taken up by a `string` you can use the extension method `GetColumns()`
 
-```diff 
-- myString.Sum(c=>Rune.ColumnWidth(c));
-+ myString.GetColumns();
+### Pos and Dim API Changes
+
+| v1 | v2 |
+|----|-----|
+| `Pos.At(x)` | `Pos.Absolute(x)` |
+| `Dim.Sized(width)` | `Dim.Absolute(width)` |
+| `Pos.Anchor()` | `Pos.GetAnchor()` |
+| `Dim.Anchor()` | `Dim.GetAnchor()` |
+
+```csharp
+// ❌ v1
+view.X = Pos.At(10);
+view.Width = Dim.Sized(20);
+
+// ✅ v2
+view.X = Pos.Absolute(10);
+view.Width = Dim.Absolute(20);
 ```
 
-## `View Life Cycle Management
+### View.AutoSize Removed
 
-In v1, @Terminal.Gui.View was derived from `Responder` which supported `IDisposable`. In v2, `Responder` has been removed and @Terminal.Gui.View is the base-class supporting `IDisposable`. 
+**v1:**
+```csharp
+view.AutoSize = true;
+```
 
-In v1, @Terminal.Gui./Terminal.Gui.Application.Init) automatically created a toplevel view and set [Application.Top](~/api/Terminal.Gui.Application.Top. In v2, @Terminal.Gui.App.Application.Init no longer automatically creates a toplevel or sets @Terminal.Gui.App.Application.Top; app developers must explicitly create the toplevel view and pass it to @Terminal.Gui.App.Application.Run (or use `Application.Run<myTopLevel>`). Developers are responsible for calling `Dispose` on any toplevel they create before exiting. 
+**v2:**
+```csharp
+view.Width = Dim.Auto();
+view.Height = Dim.Auto();
+```
 
-### How to Fix
+See [Dim.Auto Deep Dive](dimauto.md) for details.
 
-* Replace `Responder` with @Terminal.Gui.View
-* Update any code that assumes `Application.Init` automatically created a toplevel view and set `Application.Top`.
-* Update any code that assumes `Application.Init` automatically disposed of the toplevel view when the application exited.
+---
 
-## @Terminal.Gui.Pos and @Terminal.Gui.Dim types now adhere to standard C# idioms
+## Adornments
 
-* In v1, the @Terminal.Gui.Pos and @Terminal.Gui.Dim types (e.g. @Terminal.Gui.Pos.PosView) were nested classes and marked @Terminal.Gui.internal. In v2, they are no longer nested, and have appropriate public APIs. 
-* Nullabilty is enabled.
-* Methods & properties follow standards.
-* The static method that creates a @Terminal.Gui.PosAbsolute, `Pos.At`, was renamed to @Terminal.Gui.Pos.Absolute for consistency.
-* The static method that crates as @Terminal.Gui.DimAbsoulte, `Dim.Sized`, was renamed to @Terminal.Gui.Dim.Absolute for consistency.
+v2 adds `Border`, `Margin`, and `Padding` as built-in adornments.
 
-### How to Fix
+**v1:**
+```csharp
+// Custom border drawing
+view.Border = new Border { /* ... */ };
+```
 
-* Search and replace `Pos.Pos` -> `Pos`.
-* Search and replace `Dim.Dim` -> `Dim`.
-* Search and replace `Pos.At` -> `Pos.Absolute`
-* Search and replace `Dim.Sized` -> `Dim.Absolute`
-* Search and replace `Dim.Anchor` -> `Dim.GetAnchor`
-* Search and replace `Pos.Anchor` -> `Pos.GetAnchor`
+**v2:**
+```csharp
+// Built-in Border adornment
+view.BorderStyle = LineStyle.Single;
+view.Border.Thickness = new Thickness(1);
+view.Title = "My View";
+
+// Built-in Margin and Padding
+view.Margin.Thickness = new Thickness(2);
+view.Padding.Thickness = new Thickness(1);
+```
 
-## Layout Improvements
+See [Layout Deep Dive](layout.md) for complete details.
 
-In v2, the layout system has been improved to make it easier to create complex user interfaces. If you are using custom layouts in your application, you may need to update them to use the new layout system.
+---
 
-* The distinction between `Absolute Layout` and `Computed Layout` has been removed, as has the `LayoutStyle` enum. v1 drew a false distinction between these styles. 
-* @Terminal.Gui.ViewBase.View.Frame now represents the position and size of the view in the superview's coordinate system. The `Frame` property is of type `Rectangle`.
-* @Terminal.Gui.ViewBase.View.Bounds has been replaced by @Terminal.Gui.ViewBase.View.Viewport. The `Viewport` property represents the visible area of the view in its own coordinate system. The `Viewport` property is of type `Rectangle`.
-* @Terminal.Gui.ViewBase.View.GetContentSize represents the size of the view's content. This replaces `ScrollView` and `ScrollBarView` in v1. See more below.
+## Color and Attribute Changes
 
-### How to Fix
+### 24-bit TrueColor Default
 
-### `Bounds` -> `Viewport`
+v2 uses 24-bit color by default.
 
-* Remove all references ot `LayoutStyle`.
-* Rename `Bounds` to `Viewport`. The `Location` property of `Bounds` can now have non-zero values.
-* Update any code that assumed `Bounds.Location` was always `Point.Empty`.
-* Update any code that used `Bounds` to refer to the size of the view's content. Use `GetContentSize()` instead.
-* Update any code that assumed `Bounds.Size` was the same as `Frame.Size`. `Frame.Size` defines the size of the view in the superview's coordinate system, while `Viewport.Size` defines the visible area of the view in its own coordinate system.
-* Use @Terminal.Gui.ViewBase.View.GetAdornmentsThickness to get the total thickness of the view's border, margin, and padding.
-* Not assume a View can draw outside of 'Viewport'. Use the 'Margin', 'Border', and 'Padding' Adornments to do things outside of `Viewport`. View subclasses should not implement their own concept of padding or margins but leverage these `Adornments` instead. 
-* Mouse and draw events now provide coordinates relative to the `Viewport` not the `Frame`.
+```csharp
+// v1 - Limited color palette
+var color = Color.Brown;
 
-## `View.AutoSize` has been removed. Use @Terminal.Gui.Dim.Auto for width or height instead.
+// v2 - ANSI-compliant names + TrueColor
+var color = Color.Yellow; // Brown renamed
+var customColor = new Color(0xFF, 0x99, 0x00); // 24-bit RGB
+```
 
-In v1, `View.AutoSize` was used to size a view to its `Text`. In v2, `View.AutoSize` has been removed. Use @Terminal.Gui.Dim.Auto for width or height instead.
+### Attribute.Make Removed
 
-### How to Fix
+**v1:**
+```csharp
+var attr = Attribute.Make(Color.BrightMagenta, Color.Blue);
+```
+
+**v2:**
+```csharp
+var attr = new Attribute(Color.BrightMagenta, Color.Blue);
+```
 
-* Replace `View.AutoSize = true` with `View.Width = Dim.Auto` or `View.Height = Dim.Auto` as needed. See the [DimAuto Deep Dive](dimauto.md) for more information.
+### Color Name Changes
 
-## Adornments
+| v1 | v2 |
+|----|-----|
+| `Color.Brown` | `Color.Yellow` |
+
+---
 
-In v2, the `Border`, `Margin`, and `Padding` properties have been added to all views. This simplifies view development and enables a sophisticated look and feel. If you are using custom borders, margins, or padding in your application, you may need to update them to use the new properties.
+## Type Changes
 
-* `View.Border` is now of type @Terminal.Gui.Adornment. @Terminal.Gui.ViewBase.View.BorderStyle is provided as a convenience property to set the border style (`myView.BorderStyle = LineStyle.Double`).
+### Low-Level Types
 
-### How to Fix
+| v1 | v2 |
+|----|-----|
+| `Rect` | `Rectangle` |
+| `Point` | `Point` |
+| `Size` | `Size` |
 
-## Built-in Scrolling
+```csharp
+// ❌ v1
+Rect rect = new Rect(0, 0, 10, 10);
 
-In v1, scrolling was enabled by using `ScrollView` or `ScrollBarView`. In v2, the base @Terminal.Gui.View class supports scrolling inherently. The area of a view visible to the user at a given moment was previously a rectangle called `Bounds`. `Bounds.Location` was always `Point.Empty`. In v2 the visible area is a rectangle called `Viewport` which is a protal into the Views content, which can be bigger (or smaller) than the area visible to the user. Causing a view to scroll is as simple as changing `View.Viewport.Location`. The View's content is described by @Terminal.Gui.ViewBase.View.GetContentSize. See [Layout](layout.md) for details.
+// ✅ v2
+Rectangle rect = new Rectangle(0, 0, 10, 10);
+```
 
[email protected] replaces `ScrollBarView` with a much cleaner implementation of a scrollbar. In addition, @Terminal.Gui.ViewBase.View.VerticalScrollBar and @Terminal.Gui.ViewBase.View.HorizontalScrollBar provide a simple way to enable scroll bars in any View with almost no code. See See [Scrolling Deep Dive](scrolling.md) for more.
+---
 
-### How to Fix
+## Unicode and Text
 
-* Replace `ScrollView` with @Terminal.Gui.View and use `Viewport` and @Terminal.Gui.ViewBase.View.GetContentSize to control scrolling.
-* Update any code that assumed `Bounds.Location` was always `Point.Empty`.
-* Update any code that used `Bounds` to refer to the size of the view's content. Use @Terminal.Gui.ViewBase.View.GetContentSize instead.
-* Update any code that assumed `Bounds.Size` was the same as `Frame.Size`. `Frame.Size` defines the size of the view in the superview's coordinate system, while `Viewport.Size` defines the visible area of the view in its own coordinate system.
-* Replace `ScrollBarView` with @Terminal.Gui.ScrollBar. See [Scrolling Deep Dive](scrolling.md) for more.
+### NStack.ustring Removed
 
-## Updated Keyboard API
+**v1:**
+```csharp
+using NStack;
+ustring text = "Hello";
+var width = text.Sum(c => Rune.ColumnWidth(c));
+```
+
+**v2:**
+```csharp
+using System.Text;
+string text = "Hello";
+var width = text.GetColumns(); // Extension method
+```
 
-The API for handling keyboard input is significantly improved. See [Keyboard API](keyboard.md).
+### Rune Changes
+
+**v1:**
+```csharp
+// Implicit cast
+myView.AddRune(col, row, '▄');
+
+// Width
+var width = Rune.ColumnWidth(rune);
+```
+
+**v2:**
+```csharp
+// Explicit constructor
+myView.AddRune(col, row, new Rune('▄'));
+
+// Width
+var width = rune.GetColumns();
+```
+
+See [Unicode](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#unicode) for details.
+
+---
+
+## Keyboard API
+
+v2 has a completely redesigned keyboard API.
+
+### Key Class
+
+**v1:**
+```csharp
+KeyEvent keyEvent;
+if (keyEvent.KeyCode == KeyCode.Enter) { }
+```
+
+**v2:**
+```csharp
+Key key;
+if (key == Key.Enter) { }
+
+// Modifiers
+if (key.Shift) { }
+if (key.Ctrl) { }
+
+// With modifiers
+Key ctrlC = Key.C.WithCtrl;
+Key shiftF1 = Key.F1.WithShift;
+```
+
+### Key Bindings
+
+**v1:**
+```csharp
+// Override OnKeyPress
+protected override bool OnKeyPress(KeyEvent keyEvent)
+{
+    if (keyEvent.KeyCode == KeyCode.Enter)
+    {
+        // Handle
+        return true;
+    }
+    return base.OnKeyPress(keyEvent);
+}
+```
+
+**v2:**
+```csharp
+// Use KeyBindings + Commands
+AddCommand(Command.Accept, HandleAccept);
+KeyBindings.Add(Key.Enter, Command.Accept);
+
+private bool HandleAccept()
+{
+    // Handle
+    return true;
+}
+```
 
-* The @Terminal.Gui.Key class replaces the `KeyEvent` struct and provides a platform-independent abstraction for common keyboard operations. It is used for processing keyboard input and raising keyboard events. This class provides a high-level abstraction with helper methods and properties for common keyboard operations. Use this class instead of the low-level @Terminal.Gui.KeyCode enum when possible. See @Terminal.Gui.Key for more details.
-* The preferred way to enable Application-wide or View-heirarchy-dependent keystrokes is to use the @Terminal.Gui.Shortcut View or the built-in View's that utilize it, such as the @Terminal.Gui.Bar-based views.
-* The preferred way to handle single keystrokes is to use **Key Bindings**. Key Bindings map a key press to a @Terminal.Gui.Input.Command. A view can declare which commands it supports, and provide a lambda that implements the functionality of the command, using `View.AddCommand()`. Use the @Terminal.Gui.ViewBase.View.Keybindings to configure the key bindings.
-* For better consistency and user experience, the default key for closing an app or `Toplevel` is now `Esc` (it was previously `Ctrl+Q`).
-* The `Application.RootKeyEvent` method has been replaced with `Application.KeyDown`
+### Application-Wide Keys
 
-### How to Fix
+**v1:**
+```csharp
+// Hard-coded Ctrl+Q
+if (keyEvent.Key == Key.CtrlMask | Key.Q)
+{
+    Application.RequestStop();
+}
+```
 
-* Replace `KeyEvent` with `Key`
-* Use @Terminal.Gui.ViewBase.View.AddCommand to define commands your view supports.
-* Use @Terminal.Gui.ViewBase.View.Keybindings to configure key bindings to `Command`s.
-* It should be very uncommon for v2 code to override `OnKeyPressed` etc... 
-* Anywhere `Ctrl+Q` was hard-coded as the "quit key", replace with `Application.QuitKey`.
-* See *Navigation* below for more information on v2's navigation keys.
-* Replace `Application.RootKeyEvent` with `Application.KeyDown`.  If the reason for subscribing to RootKeyEvent was to enable an application-wide action based on a key-press, consider using Application.KeyBindings instead.
+**v2:**
+```csharp
+// Configurable quit key
+if (key == Application.QuitKey)
+{
+    Application.RequestStop();
+}
 
-```diff
-- Application.RootKeyEvent(KeyEvent arg)
-+ Application.KeyDown(object? sender, Key e)
+// Change the quit key
+Application.QuitKey = Key.Esc;
 ```
 
-## **@"Terminal.Gui.Input.Command" has been expanded and simplified
+### Navigation Keys
 
-In v1, the `Command` enum had duplicate entries and inconsistent naming. In v2 it has been both expanded and simplified.
+v2 has consistent, configurable navigation keys:
 
-### How To Fix
+| Key | Purpose |
+|-----|---------|
+| `Tab` | Next TabStop |
+| `Shift+Tab` | Previous TabStop |
+| `F6` | Next TabGroup |
+| `Shift+F6` | Previous TabGroup |
 
-* Update any references to old `Command` values with the updated versions.
+```csharp
+// Configurable
+Application.NextTabStopKey = Key.Tab;
+Application.PrevTabStopKey = Key.Tab.WithShift;
+Application.NextTabGroupKey = Key.F6;
+Application.PrevTabGroupKey = Key.F6.WithShift;
+```
 
-## Updated Mouse API
+See [Keyboard Deep Dive](keyboard.md) for complete details.
 
-The API for mouse input is now internally consistent and easier to use.
+---
 
-* The @Terminal.Gui.MouseEventArgs class replaces `MouseEventEventArgs`.
-* More granular APIs are provided to ease handling specific mouse actions. See [Mouse API](mouse.md).
-* Views can use the @Terminal.Gui.ViewBase.View.Highlight event to have the view be visibly highlighted on various mouse events.
-* Views can set `View.WantContinousButtonPresses = true` to have their @Terminal.Gui.Input.Command.Accept command be invoked repeatedly as the user holds a mouse button down on the view.
-* Mouse and draw events now provide coordinates relative to the `Viewport` not the `Screen`.
-* The `Application.RootMouseEvent` method has been replaced with `Application.MouseEvent`
+## Mouse API
 
-### How to Fix
+### MouseEventEventArgs → MouseEventArgs
 
-* Replace `MouseEventEventArgs` with `MouseEvent`
-* Use the @Terminal.Gui.ViewBase.View.Highlight event to have the view be visibly highlighted on various mouse events.
-* Set `View.WantContinousButtonPresses = true` to have the @Terminal.Gui.Input.Command.Accept command be invoked repeatedly as the user holds a mouse button down on the view.
-* Update any code that assumed mouse events provided coordinates relative to the `Screen`.
-* Replace `Application.RootMouseEvent` with `Application.MouseEvent`.  
+**v1:**
+```csharp
+void HandleMouse(MouseEventEventArgs args) { }
+```
 
-```diff
-- Application.RootMouseEvent(KeyEvent arg)
-+ Application.MouseEvent(object? sender, MouseEventArgs mouseEvent)
+**v2:**
+```csharp
+void HandleMouse(object? sender, MouseEventArgs args) { }
 ```
 
-## Navigation - `Cursor`, `Focus`, `TabStop` etc... 
+### Mouse Coordinates
 
-The cursor and focus system has been redesigned in v2 to be more consistent and easier to use. If you are using custom cursor or focus logic in your application, you may need to update it to use the new system.
+**v1:**
+- Mouse coordinates were screen-relative
+
+**v2:**
+- Mouse coordinates are now **Viewport-relative**
+
+```csharp
+// v2 - Viewport-relative coordinates
+view.MouseClick += (s, e) =>
+{
+    // e.Position is relative to view's Viewport
+    var x = e.Position.X; // 0 = left edge of viewport
+    var y = e.Position.Y; // 0 = top edge of viewport
+};
+```
 
-### Cursor
+### Highlight Event
 
-In v1, whether the cursor (the flashing caret) was visible or not was controlled by `View.CursorVisibility` which was an enum extracted from Ncruses/Terminfo. It only works in some cases on Linux, and only partially with `WindowsDriver`. The position of the cursor was the same as `ConsoleDriver.Row`/`Col` and determined by the last call to `ConsoleDriver.Move`. `View.PositionCursor()` could be overridden by views to cause `Application` to call `ConsoleDriver.Move` on behalf of the app and to manage setting `CursorVisibility`. This API was confusing and bug-prone.
+v2 adds a `Highlight` event for visual feedback:
 
-In v2, the API is (NOT YET IMPLEMENTED) simplified. A view simply reports the style of cursor it wants and the Viewport-relative location:
+```csharp
+view.Highlight += (s, e) =>
+{
+    // Provide visual feedback on mouse hover
+};
+view.HighlightStyle = HighlightStyle.Hover;
+```
 
-* `public Point? CursorPosition`
-    - If `null` the cursor is not visible
-    - If `{}` the cursor is visible at the `Point`.
-* `public event EventHandler<LocationChangedEventArgs>? CursorPositionChanged`
-* `public int? CursorStyle`
-	- If `null` the default cursor style is used.
-	- If `{}` specifies the style of cursor. See [cursor.md](cursor.md) for more.
-* `Application` now has APIs for querying available cursor styles.
-* The details in `ConsoleDriver` are no longer available to applications.	
+See [Mouse Deep Dive](mouse.md) for complete details.
 
-#### How to Fix (Cursor API)
+---
 
-* Use @Terminal.Gui.ViewBase.View.CursorPosition to set the cursor position in a view. Set @Terminal.Gui.ViewBase.View.CursorPosition to `null` to hide the cursor.
-* Set @Terminal.Gui.ViewBase.View.CursorVisibility to the cursor style you want to use.
-* Remove any overrides of `OnEnter` and `OnLeave` that explicitly change the cursor.
+## Navigation Changes
 
-### Focus
+### Focus Properties
 
-See [navigation.md](navigation.md) for more details.
-See also [Keyboard](keyboard.md) where HotKey is covered more deeply...
+**v1:**
+```csharp
+view.CanFocus = true; // Default was true
+```
 
-* In v1, `View.CanFocus` was `true` by default. In v2, it is `false`. Any `View` subclass that wants to be focusable must set `CanFocus = true`.
-* In v1 it was not possible to remove focus from a view. `HasFocus` as a get-only property. In v2, `view.HasFocus` can be set as well. Setting to `true` is equivalent to calling `view.SetFocus`. Setting to `false` is equivalent to calling `view.SuperView.AdvanceFocus` (which might not actually cause `view` to stop having focus). 
-* In v1, calling `super.Add (view)` where `view.CanFocus == true` caused all views up the hierarchy (all SuperViews) to get `CanFocus` set to `true` as well. In v2, developers need to explicitly set `CanFocus` for any view in the view-hierarchy where focus is desired. This simplifies the implementation and removes confusing automatic behavior. 
-* In v1, if `view.CanFocus == true`, `Add` would automatically set `TabStop`. In v2, the automatic setting of `TabStop` in `Add` is retained because it is not overly complex to do so and is a nice convenience for developers to not have to set both `Tabstop` and `CanFocus`. Note v2 does NOT automatically change `CanFocus` if `TabStop` is changed.
-* `view.TabStop` now describes the behavior of a view in the focus chain. the `TabBehavior` enum includes `NoStop` (the view may be focusable, but not via next/prev keyboard nav), `TabStop` (the view may be focusable, and `NextTabStop`/`PrevTabStop` keyboard nav will stop), `TabGroup` (the view may be focusable, and `NextTabGroup`/`PrevTabGroup` keyboard nav will stop). 
-* In v1, the `View.Focused` property was a cache of which view in `SubViews/TabIndexes` had `HasFocus == true`. There was a lot of logic for keeping this property in sync. In v2, `View.Focused` is a get-only, computed property. 
-* In v1, the `View.MostFocused` property recursed down the subview-hierarchy on each get. In addition, because only one View in an application can be the "most focused", it doesn't make sense for this property to be on every View. In v2, this API is removed. Use `Application.Navigation.GetFocused()` instead.
-* The v1 APIs `View.EnsureFocus`/`FocusNext`/`FocusPrev`/`FocusFirst`/`FocusLast` are replaced in v2 with these APIs that accomplish the same thing, more simply.
-  - `public bool AdvanceFocus (NavigationDirection direction, TabBehavior? behavior)`  
-  - `public bool FocusDeepest (NavigationDirection direction, TabBehavior? behavior)` 
-* In v1, the `View.OnEnter/Enter` and `View.OnLeave/Leave` virtual methods/events could be used to notify that a view had gained or lost focus, but had confusing semantics around what it mean to override (requiring calling `base`) and bug-ridden behavior on what the return values signified. The "Enter" and "Leave" terminology was confusing. In v2, `View.OnHasFocusChanging/HasFocusChanging` and `View.OnHasFocusChanged/HasFocusChanged` replace `View.OnEnter/Enter` and `View.OnLeave/Leave`. These virtual methods/events follow standard Terminal.Gui event patterns. The `View.OnHasFocusChanging/HasFocusChanging` event supports being cancelled.
-* In v1, the concept of `Mdi` views included a large amount of complex code (in `Toplevel` and `Application`) for dealing with navigation across overlapped Views. This has all been radically simplified in v2. Any View can work in an "overlapped" or "tiled" way. See [navigation.md](navigation.md) for more details.
-* The `View.TabIndex` and `View.TabIndexes` have been removed. Change the order of the views in `View.SubViews` to change the navigation order (using, for example `View.MoveSubViewTowardsStart()`).
+**v2:**
+```csharp
+view.CanFocus = true; // Default is FALSE - must opt-in
+```
 
-### How to Fix (Focus API)
+**Important:** In v2, `CanFocus` defaults to `false`. Views that want focus must explicitly set it.
 
-* Set @Terminal.Gui.ViewBase.View.CanFocus to `true` for any View sub-class that wants to be focusable.
-* Use @Terminal.Gui.App.Application.Navigation.GetFocused to get the most focused view in the application.
-* Use @Terminal.Gui.App.Application.Navigation.AdvanceFocus to cause focus to change.
+### Focus Changes
 
-### Keyboard Navigation
+**v1:**
+```csharp
+// HasFocus was read-only
+bool hasFocus = view.HasFocus;
+```
 
-In v2, `HotKey`s can be used to navigate across the entire application view-hierarchy. They work independently of `Focus`. This enables a user to navigate across a complex UI of nested subviews if needed (even in overlapped scenarios). An example use-case is the `AllViewsTester` scenario.
+**v2:**
+```csharp
+// HasFocus can be set
+view.HasFocus = true; // Equivalent to SetFocus()
+view.HasFocus = false; // Equivalent to SuperView.AdvanceFocus()
+```
 
-In v2, unlike v1, multiple Views in an application (even within the same SuperView) can have the same `HotKey`. Each press of the `HotKey` will invoke the next `HotKey` across the View hierarchy (NOT IMPLEMENTED YET)*
+### TabStop Behavior
 
-In v1, the keys used for navigation were both hard-coded and configurable, but in an inconsistent way. `Tab` and `Shift+Tab` worked consistently for navigating between SubViews, but were not configurable. `Ctrl+Tab` and `Ctrl+Shift+Tab` navigated across `Overlapped` views and had configurable "alternate" versions (`Ctrl+PageDown` and `Ctrl+PageUp`).
+**v1:**
+```csharp
+view.TabStop = true; // Boolean
+```
 
-In v2, this is made consistent and configurable:
+**v2:**
+```csharp
+view.TabStop = TabBehavior.TabStop; // Enum with more options
 
-- `Application.NextTabStopKey` (`Key.Tab`) - Navigates to the next subview that is a `TabStop` (see below). If there is no next, the first subview that is a `TabStop` will gain focus.
-- `Application.PrevTabStopKey` (`Key.Tab.WithShift`) - Opposite of `Application.NextTabStopKey`.
-- `Key.CursorRight` - Operates identically to `Application.NextTabStopKey`.
-- `Key.CursorDown` - Operates identically to `Application.NextTabStopKey`.
-- `Key.CursorLeft` - Operates identically to `Application.PrevTabStopKey`.
-- `Key.CursorUp` - Operates identically to `Application.PrevTabStopKey`.
-- `Application.NextTabGroupKey` (`Key.F6`) - Navigates to the next view in the view-hierarchy that is a `TabGroup` (see below). If there is no next, the first view which is a `TabGroup`` will gain focus.
-- `Application.PrevTabGroupKey` (`Key.F6.WithShift`) - Opposite of `Application.NextTabGroupKey`.
+// Options:
+// - NoStop: Focusable but not via Tab
+// - TabStop: Normal tab navigation
+// - TabGroup: Advance via F6
+```
 
-`F6` was chosen to match [Windows](https://learn.microsoft.com/en-us/windows/apps/design/input/keyboard-accelerators#common-keyboard-accelerators)
+### Navigation Events
 
-These keys are all registered as `KeyBindingScope.Application` key bindings by `Application`. Because application-scoped key bindings have the lowest priority, Views can override the behaviors of these keys (e.g. `TextView` overrides `Key.Tab` by default, enabling the user to enter `\t` into text). The `AllViews_AtLeastOneNavKey_Leaves` unit test ensures all built-in Views have at least one of the above keys that can advance. 
+**v1:**
+```csharp
+view.Enter += (s, e) => { }; // Gained focus
+view.Leave += (s, e) => { }; // Lost focus
+```
 
-### How to Fix (Keyboard Navigation)
+**v2:**
+```csharp
+view.HasFocusChanging += (s, e) => 
+{ 
+    // Before focus changes (cancellable)
+    if (preventFocusChange)
+        e.Cancel = true;
+};
+
+view.HasFocusChanged += (s, e) => 
+{ 
+    // After focus changed
+    if (e.Value)
+        Console.WriteLine("Gained focus");
+    else
+        Console.WriteLine("Lost focus");
+};
+```
 
-...
+See [Navigation Deep Dive](navigation.md) for complete details.
 
-## Button.Clicked Event Renamed
+---
 
-The `Button.Clicked` event has been renamed `Button.Accepting`
+## Scrolling Changes
 
-## How to Fix
+### ScrollView Removed
 
-Rename all instances of `Button.Clicked` to `Button.Accepting`.  Note the signature change to mouse events below.
+**v1:**
+```csharp
+var scrollView = new ScrollView
+{
+    ContentSize = new Size(100, 100),
+    ShowHorizontalScrollIndicator = true,
+    ShowVerticalScrollIndicator = true
+};
+```
 
-```diff
-- btnLogin.Clicked 
-+ btnLogin.Accepting
+**v2:**
+```csharp
+// Built-in scrolling on every View
+var view = new View();
+view.SetContentSize(new Size(100, 100));
+
+// Built-in scrollbars
+view.VerticalScrollBar.Visible = true;
+view.HorizontalScrollBar.Visible = true;
+view.VerticalScrollBar.AutoShow = true;
 ```
 
-Alternatively, if you want to have key events as well as mouse events to fire an event, use `Button.Accepting`.
+### Scrolling API
+
+**v2:**
+```csharp
+// Set content larger than viewport
+view.SetContentSize(new Size(100, 100));
+
+// Scroll by changing Viewport location
+view.Viewport = view.Viewport with { Location = new Point(10, 10) };
+
+// Or use helper methods
+view.ScrollVertical(5);
+view.ScrollHorizontal(3);
+```
 
-## Events now use `object sender, EventArgs args` signature
+See [Scrolling Deep Dive](scrolling.md) for complete details.
 
-Previously events in Terminal.Gui used a mixture of `Action` (no arguments), `Action<string>` (or other raw datatype) and `Action<EventArgs>`. Now all events use the `EventHandler<EventArgs>` [standard .net design pattern](https://learn.microsoft.com/en-us/dotnet/csharp/event-pattern#event-delegate-signatures).
+---
 
-For example, `event Action`<long> TimeoutAdded` has become `event EventHandler<TimeoutEventArgs> TimeoutAdded`
+## Event Pattern Changes
 
-This change was made for the following reasons:
+v2 standardizes all events to use `object sender, EventArgs args` pattern.
 
-- Event parameters are now individually named and documented (with xmldoc)
-- Future additions to event parameters can be made without being breaking changes (i.e. adding new properties to the EventArgs class)
+### Button.Clicked → Button.Accepting
 
-For example:
+**v1:**
+```csharp
+button.Clicked += () => { /* do something */ };
+```
 
+**v2:**
 ```csharp
+button.Accepting += (s, e) => { /* do something */ };
+```
 
-public class TimeoutEventArgs : EventArgs {
+### Event Signatures
 
-	/// <summary>
-	/// Gets the <see cref="DateTime.Ticks"/> in UTC time when the 
-	/// <see cref="Timeout"/> will next execute after.
-	/// </summary>
-	public long Ticks { get; }
+**v1:**
+```csharp
+// Various patterns
+event Action SomeEvent;
+event Action<string> OtherEvent;
+event Action<EventArgs> ThirdEvent;
+```
 
-[...]
-}
+**v2:**
+```csharp
+// Consistent pattern
+event EventHandler<EventArgs>? SomeEvent;
+event EventHandler<EventArgs<string>>? OtherEvent;
+event EventHandler<CancelEventArgs<bool>>? ThirdEvent;
 ```
 
-## How To Fix
-If you previously had a lambda expression, you can simply add the extra arguments:
+**Benefits:**
+- Named parameters
+- Cancellable events via `CancelEventArgs`
+- Future-proof (new properties can be added)
+
+---
+
+## View-Specific Changes
 
-```diff
-- btnLogin.Clicked += () => { /*do something*/ };
-+ btnLogin.Accepting += (s,e) => { /*do something*/ };
+### CheckBox
+
+**v1:**
+```csharp
+var cb = new CheckBox("_Checkbox", true);
+cb.Toggled += (e) => { };
+cb.Toggle();
 ```
-Note that the event name has also changed as noted above.
 
-If you have used a named method instead of a lamda you will need to update the signature e.g.
+**v2:**
+```csharp
+var cb = new CheckBox 
+{ 
+    Title = "_Checkbox",
+    CheckState = CheckState.Checked
+};
+cb.CheckStateChanging += (s, e) => 
+{
+    e.Cancel = preventChange;
+};
+cb.AdvanceCheckState();
+```
+
+### StatusBar
 
-```diff
-- private void MyButton_Clicked ()
-+ private void MyButton_Clicked (object sender, EventArgs e)
+**v1:**
+```csharp
+var statusBar = new StatusBar(
+    new StatusItem[]
+    {
+        new StatusItem(Application.QuitKey, "Quit", () => Quit())
+    }
+);
 ```
 
-## `ReDraw` is now `Draw`
+**v2:**
+```csharp
+var statusBar = new StatusBar(
+    new Shortcut[] 
+    { 
+        new Shortcut(Application.QuitKey, "Quit", Quit) 
+    }
+);
+```
 
-### How to Fix
+### PopoverMenu
 
-* Replace `ReDraw` with `Draw`
-* Mouse and draw events now provide coordinates relative to the `Viewport` not the `Frame`.
+v2 replaces `ContextMenu` with `PopoverMenu`:
 
-## No more nested classes
+**v1:**
+```csharp
+var contextMenu = new ContextMenu();
+```
 
-All public classes that were previously [nested classes](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/nested-types) are now in the root namespace as their own classes.
+**v2:**
+```csharp
+var popoverMenu = new PopoverMenu();
+```
+
+### MenuItem
 
-### How To Fix
-Replace references to nested types with the new standalone version
+**v1:**
+```csharp
+new MenuItem(
+    "Copy",
+    "",
+    CopyGlyph,
+    null,
+    null,
+    (KeyCode)Key.G.WithCtrl
+)
+```
 
-```diff
-- var myTab = new TabView.Tab();
-+ var myTab = new Tab();
+**v2:**
+```csharp
+new MenuItem(
+    "Copy",
+    "",
+    CopyGlyph,
+    Key.G.WithCtrl
+)
 ```
 
-## View and Text Alignment Changes
+---
 
-In v1, both `TextAlignment` and `VerticalTextAlignment` enums were used to align text in views. In v2, these enums have been replaced with the @Terminal.Gui.Alignment enum. The @Terminal.Gui.ViewBase.View.TextAlignment property controls horizontal text alignment and the @Terminal.Gui.ViewBase.View.VerticalTextAlignment property controls vertical text alignment.
+## Disposal and Resource Management
 
-v2 now supports @Terminal.Gui.Pos.Align which enables views to be easily aligned within their Superview. 
+v2 implements proper `IDisposable` throughout.
 
-The @Terminal.Gui.Aligner class makes it easy to align elements (text, Views, etc...) within a container. 
+### View Disposal
 
-### How to Fix
+```csharp
+// v1 - No explicit disposal needed
+var view = new View();
+Application.Run(view);
+Application.Shutdown();
+
+// v2 - Explicit disposal required
+var view = new View();
+app.Run(view);
+view.Dispose();
+app.Dispose();
+```
 
-* Replace `VerticalAlignment.Middle` is now @Terminal.Gui.Alignment.Center. 
+### Disposal Patterns
 
-## `StatusBar`- `StatusItem` is replaced by `Shortcut`
+```csharp
+// ✅ Best practice - using statement
+using (var app = Application.Create().Init())
+{
+    using (var view = new View())
+    {
+        app.Run(view);
+    }
+}
 
[email protected] has been upgraded to utilize @Terminal.Gui.Shortcut.
+// ✅ Alternative - explicit try/finally
+var app = Application.Create();
+try
+{
+    app.Init();
+    var view = new View();
+    try
+    {
+        app.Run(view);
+    }
+    finally
+    {
+        view.Dispose();
+    }
+}
+finally
+{
+    app.Dispose();
+}
+```
 
-### How to Fix
+### SubView Disposal
 
-```diff
--  var statusBar = new StatusBar (
--                                       new StatusItem []
--                                       {
--                                           new (
--                                                Application.QuitKey,
--                                                $"{Application.QuitKey} to Quit",
--                                                () => Quit ()
--                                               )
--                                       }
--                                      );
-+ var statusBar = new StatusBar (new Shortcut [] { new (Application.QuitKey, "Quit", Quit) });
+When a View is disposed, it automatically disposes all SubViews:
+
+```csharp
+var container = new View();
+var child1 = new View();
+var child2 = new View();
+
+container.Add(child1, child2);
+
+// Disposes container, child1, and child2
+container.Dispose();
 ```
 
-## `CheckBox` - API renamed and simplified
+See [Resource Management](#disposal-and-resource-management) for complete details.
+
+---
 
-In v1 `CheckBox` used `bool?` to represent the 3 states. To support consistent behavior for the `Accept` event, `CheckBox` was refactored to use the new `CheckState` enum instead of `bool?`.
+## API Terminology Changes
 
-Additionally, the `Toggle` event was renamed `CheckStateChanging` and made cancelable. The `Toggle` method was renamed to `AdvanceCheckState`.
+v2 modernizes terminology for clarity:
 
-### How to Fix
+### Application.Top → Application.TopRunnable
 
-```diff
--var cb = new CheckBox ("_Checkbox", true); {
--				X = Pos.Right (label) + 1,
--				Y = Pos.Top (label) + 2
--			};
--			cb.Toggled += (e) => {
--			};
--           cb.Toggle ();
-+
-+var cb = new CheckBox ()
-+{ 
-+	Title = "_Checkbox",
-+	CheckState = CheckState.Checked
-+}
-+cb.CheckStateChanging += (s, e) =>
-+{	
-+	e.Cancel = preventChange;
-+}
-+preventChange = false;
-+cb.AdvanceCheckState ();
+**v1:**
+```csharp
+Application.Top.SetNeedsDraw();
 ```
 
-## `MainLoop` is no longer accessible from `Application`
+**v2:**
+```csharp
+// Use TopRunnable (or TopRunnableView for View reference)
+app.TopRunnable?.SetNeedsDraw();
+app.TopRunnableView?.SetNeedsDraw();
+
+// From within a view
+App?.TopRunnableView?.SetNeedsDraw();
+```
 
-In v1, you could add timeouts via `Application.MainLoop.AddTimeout` among other things.  In v2, the `MainLoop` object is internal to `Application` and methods previously accessed via `MainLoop` can now be accessed directly via `Application`
+**Why "TopRunnable"?**
+- Clearly indicates it's the top of the runnable session stack
+- Aligns with `IRunnable` architecture
+- Works with any `IRunnable`, not just `Toplevel`
 
-### How to Fix
+### Application.TopLevels → Application.SessionStack
 
-```diff
-- Application.MainLoop.AddTimeout (TimeSpan time, Func<MainLoop, bool> callback)
-+ Application.AddTimeout (TimeSpan time, Func<bool> callback)
+**v1:**
+```csharp
+foreach (var tl in Application.TopLevels)
+{
+    // Process
+}
 ```
 
-## `SendSubViewXXX` renamed and corrected
+**v2:**
+```csharp
+foreach (var token in app.SessionStack)
+{
+    var runnable = token.Runnable;
+    // Process
+}
 
-In v1, the `View` methods to move SubViews within the SubViews list were poorly named and actually operated in reverse of what their names suggested.
+// Count of sessions
+int sessionCount = app.SessionStack.Count;
+```
 
-In v2, these methods have been named correctly.
+**Why "SessionStack"?**
+- Describes both content (sessions) and structure (stack)
+- Aligns with `SessionToken` terminology
+- Follows .NET naming patterns
 
-- `SendSubViewToBack` -> `MoveSubViewToStart` - Moves the specified subview to the start of the list.
-- `SendSubViewBackward` -> `MoveSubViewTowardsStart` - Moves the specified subview one position towards the start of the list.
-- `SendSubViewToFront` -> `MoveSubViewToEnd` - Moves the specified subview to the end of the list.
-- `SendSubViewForward` -> `MoveSubViewTowardsEnd` - Moves the specified subview one position towards the end of the list.
+### View Arrangement
 
-## `Mdi` Replaced by `ViewArrangement.Overlapped`
+**v1:**
+```csharp
+view.SendSubViewToBack();
+view.SendSubViewBackward();
+view.SendSubViewToFront();
+view.SendSubViewForward();
+```
 
-In v1, it apps with multiple overlapping views could be created using a set of APIs spread across `Application` (e.g. `Application.MdiTop`) and `Toplevel` (e.g. `IsMdiContainer`). This functionality has been replaced in v2 with @Terminal.Gui.ViewBase.View.Arrangement. Specifically, overlapped views with @Terminal.Gui.ViewBase.View.Arrangement having the @Terminal.Gui.ViewBase.ViewArrangement.Overlapped flag set will be arranged in an overlapped fashion using the order in their SuperView's subview list as the Z-order. 
+**v2:**
+```csharp
+// Fixed naming (methods worked opposite to their names in v1)
+view.MoveSubViewToStart();
+view.MoveSubViewTowardsStart();
+view.MoveSubViewToEnd();
+view.MoveSubViewTowardsEnd();
+```
 
-Setting the @Terminal.Gui.ViewBase.ViewArrangement.Movable flag will enable the overlapped views to be movable with the mouse or keyboard (`Ctrl+F5` to activate).
+### Mdi → ViewArrangement.Overlapped
 
-Setting the @Terminal.Gui.ViewBase.ViewArrangement.Sizable flag will enable the overlapped views to be resized with the mouse or keyboard (`Ctrl+F5` to activate).
+**v1:**
+```csharp
+Application.MdiTop = true;
+toplevel.IsMdiContainer = true;
+```
+
+**v2:**
+```csharp
+view.Arrangement = ViewArrangement.Overlapped;
+
+// Additional flags
+view.Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable;
+```
+
+See [Arrangement Deep Dive](arrangement.md) for complete details.
 
-In v1, only Views derived from `Toplevel` could be overlapped. In v2, any view can be.
+---
 
-v1 conflated the concepts of 
+## Complete Migration Example
 
-## `PopoverMenu` replaced by `PopoverMenu`
+Here's a complete v1 to v2 migration:
 
-`PopoverMenu` replaces `ContrextMenu`. 
+**v1:**
+```csharp
+using NStack;
+using Terminal.Gui;
+
+Application.Init();
 
-## `MenuItem` is now based on `Shortcut`
+var win = new Window(new Rect(0, 0, 50, 20), "Hello");
 
+var label = new Label(1, 1, "Name:");
 
-```diff
-new (
-      Strings.charMapCopyGlyph,
-      "",
-      CopyGlyph,
--      null,
--      null,
-      (KeyCode)Key.G.WithCtrl
-     ),
-```	
+var textField = new TextField(10, 1, 30, "");
 
-## Others...
+var button = new Button(10, 3, "OK");
+button.Clicked += () =>
+{
+    MessageBox.Query(50, 7, "Info", $"Hello, {textField.Text}", "Ok");
+};
 
-* `View` and all subclasses support `IDisposable` and must be disposed (by calling `view.Dispose ()`) by whatever code owns the instance when the instance is longer needed. 
+win.Add(label, textField, button);
 
-* To simplify programming, any `View` added as a SubView another `View` will have it's lifecycle owned by the Superview; when a `View` is disposed, it will call `Dispose` on all the items in the `SubViews` property. Note this behavior is the same as it was in v1, just clarified.
+Application.Top.Add(win);
+Application.Run();
+Application.Shutdown();
+```
 
-* In v1, `Application.End` called `Dispose ()` on @Terminal.Gui.App.Application.Top (via `Runstate.Toplevel`). This was incorrect as it meant that after `Application.Run` returned, `Application.Top` had been disposed, and any code that wanted to interrogate the results of `Run` by accessing `Application.Top` only worked by accident. This is because GC had not actually happened; if it had the application would have crashed. In v2 `Application.End` does NOT call `Dispose`, and it is the caller to `Application.Run` who is responsible for disposing the `Toplevel` that was either passed to `Application.Run (View)` or created by `Application.Run<T> ()`.
+**v2:**
+```csharp
+using System;
+using Terminal.Gui;
+
+using (var app = Application.Create().Init())
+{
+    var win = new Window
+    {
+        Title = "Hello",
+        Width = 50,
+        Height = 20
+    };
+
+    var label = new Label
+    {
+        Text = "Name:",
+        X = 1,
+        Y = 1
+    };
+
+    var textField = new TextField
+    {
+        X = 10,
+        Y = 1,
+        Width = 30
+    };
+
+    var button = new Button
+    {
+        Text = "OK",
+        X = 10,
+        Y = 3
+    };
+    button.Accepting += (s, e) =>
+    {
+        MessageBox.Query(app, "Info", $"Hello, {textField.Text}", "Ok");
+    };
+
+    win.Add(label, textField, button);
+
+    app.Run(win);
+    win.Dispose();
+}
+```
 
-* Any code that creates a `Toplevel`, either by using `top = new()` or by calling either `top = Application.Run ()` or `top = ApplicationRun<T>()` must call `top.Dispose` when complete. The exception to this is if `top` is passed to `myView.Add(top)` making it a subview of `myView`. This is because the semantics of `Add` are that the `myView` takes over responsibility for the subviews lifetimes. Of course, if someone calls `myView.Remove(top)` to remove said subview, they then re-take responsbility for `top`'s lifetime and they must call `top.Dispose`.
+---
+
+## Summary of Major Breaking Changes
+
+| Category | v1 | v2 |
+|----------|----|----|
+| **Application** | Static `Application` | `IApplication` instances via `Application.Create()` |
+| **Disposal** | Automatic | Explicit (`IDisposable` pattern) |
+| **View Construction** | Constructors with Rect | Initializers with X, Y, Width, Height |
+| **Layout** | Absolute/Computed distinction | Unified Pos/Dim system |
+| **Colors** | Limited palette | 24-bit TrueColor default |
+| **Types** | `Rect`, `NStack.ustring` | `Rectangle`, `System.String` |
+| **Keyboard** | `KeyEvent`, hard-coded keys | `Key`, configurable bindings |
+| **Mouse** | Screen-relative | Viewport-relative |
+| **Scrolling** | `ScrollView` | Built-in on all Views |
+| **Focus** | `CanFocus` default true | `CanFocus` default false |
+| **Navigation** | `Enter`/`Leave` events | `HasFocusChanging`/`HasFocusChanged` |
+| **Events** | Mixed patterns | Standard `EventHandler<EventArgs>` |
+| **Terminology** | `Application.Top`, `TopLevels` | `TopRunnable`, `SessionStack` |
+
+---
+
+## Additional Resources
+
+- [Application Deep Dive](application.md) - Complete application architecture
+- [View Deep Dive](View.md) - View system details
+- [Layout Deep Dive](layout.md) - Comprehensive layout guide
+- [Keyboard Deep Dive](keyboard.md) - Keyboard input handling
+- [Mouse Deep Dive](mouse.md) - Mouse input handling
+- [Navigation Deep Dive](navigation.md) - Focus and navigation
+- [Scrolling Deep Dive](scrolling.md) - Built-in scrolling system
+- [Arrangement Deep Dive](arrangement.md) - Movable/resizable views
+- [Configuration Deep Dive](config.md) - Configuration system
+- [What's New in v2](newinv2.md) - New features overview
+
+---
+
+## Getting Help
+
+- [GitHub Discussions](https://github.com/gui-cs/Terminal.Gui/discussions)
+- [GitHub Issues](https://github.com/gui-cs/Terminal.Gui/issues)
+- [API Documentation](~/api/index.md)