Fixes #4419, #4148, #4408 - Toplevel is GONE - Replaced by Runnable

.github/workflows/README.md

@@ -0,0 +1,79 @@
+## CI/CD Workflows
+
+The repository uses multiple GitHub Actions workflows. What runs and when:
+
+### 1) Build Solution (`.github/workflows/build.yml`)
+
+- **Triggers**: push and pull_request to `v2_release`, `v2_develop` (ignores `**.md`); supports `workflow_call`
+- **Runner/timeout**: `ubuntu-latest`, 10 minutes
+- **Steps**:
+- Checkout and setup .NET 8.x GA
+- `dotnet restore`
+- Build Debug: `dotnet build --configuration Debug --no-restore -property:NoWarn=0618%3B0612`
+- Build Release (library): `dotnet build Terminal.Gui/Terminal.Gui.csproj --configuration Release --no-incremental --force -property:NoWarn=0618%3B0612`
+- Pack Release: `dotnet pack Terminal.Gui/Terminal.Gui.csproj --configuration Release --output ./local_packages -property:NoWarn=0618%3B0612`
+- Restore NativeAot/SelfContained examples, then restore solution again
+- Build Release for `Examples/NativeAot` and `Examples/SelfContained`
+- Build Release solution
+- Upload artifacts named `build-artifacts`, retention 1 day
+
+### 2) Build & Run Unit Tests (`.github/workflows/unit-tests.yml`)
+
+- **Triggers**: push and pull_request to `v2_release`, `v2_develop` (ignores `**.md`)
+- **Matrix**: Ubuntu/Windows/macOS
+- **Timeout**: 15 minutes per job
+- **Process**:
+1. Calls build workflow to build solution once
+2. Downloads build artifacts
+3. Runs `dotnet restore` (required for `--no-build` to work)
+4. **Performance optimizations**:
+   - Disables Windows Defender on Windows runners (significant speedup)
+   - Collects code coverage **only on Linux** (ubuntu-latest) for performance
+   - Windows and macOS skip coverage collection to reduce test time
+   - Increased blame-hang-timeout to 120s for Windows/macOS (60s for Linux)
+5. Runs two test jobs:
+   - **Non-parallel UnitTests**: `Tests/UnitTests` with blame/diag flags; `xunit.stopOnFail=false`
+   - **Parallel UnitTestsParallelizable**: `Tests/UnitTestsParallelizable` with blame/diag flags; `xunit.stopOnFail=false`
+6. Uploads test logs and diagnostic data from all runners
+7. **Uploads code coverage to Codecov only from Linux runner**
+
+**Test results**: All tests output to unified `TestResults/` directory at repository root
+
+### 3) Build & Run Integration Tests (`.github/workflows/integration-tests.yml`)
+
+- **Triggers**: push and pull_request to `v2_release`, `v2_develop` (ignores `**.md`)
+- **Matrix**: Ubuntu/Windows/macOS
+- **Timeout**: 15 minutes
+- **Process**:
+1. Calls build workflow
+2. Downloads build artifacts
+3. Runs `dotnet restore`
+4. **Performance optimizations** (same as unit tests):
+   - Disables Windows Defender on Windows runners
+   - Collects code coverage **only on Linux**
+   - Increased blame-hang-timeout to 120s for Windows/macOS
+5. Runs IntegrationTests with blame/diag flags; `xunit.stopOnFail=true`
+6. Uploads logs per-OS
+7. **Uploads coverage to Codecov only from Linux runner**
+
+### 4) Publish to NuGet (`.github/workflows/publish.yml`)
+
+- **Triggers**: push to `v2_release`, `v2_develop`, and tags `v*`(ignores `**.md`)
+- Uses GitVersion to compute SemVer, builds Release, packs with symbols, and pushes to NuGet.org using `NUGET_API_KEY`
+
+### 5) Build and publish API docs (`.github/workflows/api-docs.yml`)
+
+- **Triggers**: push to `v1_release` and `v2_develop`
+- Builds DocFX site on Windows and deploys to GitHub Pages when `ref_name` is `v2_release` or `v2_develop`
+
+
+### Replicating CI Locally
+
+```bash
+# Full CI sequence:
+dotnet restore
+dotnet build --configuration Debug --no-restore
+dotnet test Tests/UnitTests --no-build --verbosity normal
+dotnet test Tests/UnitTestsParallelizable --no-build --verbosity normal
+dotnet build --configuration Release --no-restore
+```

.github/workflows/unit-tests.yml

@@ -157,10 +157,10 @@ jobs:
     - name: Run UnitTestsParallelizable (10 iterations with varying parallelization)
       shell: bash
       run: |
-        # Run tests 10 times with different parallelization settings to expose concurrency issues
-        for RUN in {1..10}; do
+        # Run tests 3 times with different parallelization settings to expose concurrency issues
+        for RUN in {1..3}; do
           echo "============================================"
-          echo "Starting test run $RUN of 10"
+          echo "Starting test run $RUN of 3"
           echo "============================================"
           
           # Use a combination of run number and timestamp to create different execution patterns

CONTRIBUTING.md

@@ -7,19 +7,16 @@ Welcome! This guide provides everything you need to know to contribute effective
 ## Table of Contents
 
 - [Project Overview](#project-overview)
-- [Building and Testing](#building-and-testing)
+- [Key Architecture Concepts](#key-architecture-concepts)
 - [Coding Conventions](#coding-conventions)
+- [Building and Testing](#building-and-testing)
 - [Testing Requirements](#testing-requirements)
 - [API Documentation Requirements](#api-documentation-requirements)
 - [Pull Request Guidelines](#pull-request-guidelines)
 - [CI/CD Workflows](#cicd-workflows)
 - [Repository Structure](#repository-structure)
 - [Branching Model](#branching-model)
-- [Key Architecture Concepts](#key-architecture-concepts)
 - [What NOT to Do](#what-not-to-do)
-- [Additional Resources](#additional-resources)
-
----
 
 ## Project Overview
 
@@ -32,8 +29,18 @@ Welcome! This guide provides everything you need to know to contribute effective
 - **Version**: v2 (Alpha), v1 (maintenance mode)
 - **Branching**: GitFlow model (v2_develop is default/active development)
 
----
+## Key Architecture Concepts
+
+**⚠️ CRITICAL - AI Agents MUST understand these concepts before starting work.**
 
+- **Application Lifecycle** - How `Application.Init`, `Application.Run`, and `Application.Shutdown` work - [Application Deep Dive](./docfx/docs/application.md)
+- **Cancellable Workflow Patern** - [CWP Deep Dive](./docfx/docs/cancellable-work-pattern.md)
+- **View Hierarchy** - Understanding `View`, `Runnable`, `Window`, and view containment - [View Deep Dive](./docfx/docs/View.md)
+- **Layout System** - Pos, Dim, and automatic layout -  [Layout System](./docfx/docs/layout.md)
+- **Event System** - How keyboard, mouse, and application events flow - [Events Deep Dive](./docfx/docs/events.md)
+- **Driver Architecture** - How console drivers abstract platform differences - [Drivers](./docfx/docs/drivers.md)
+- **Drawing Model** - How rendering works with Attributes, Colors, and Glyphs  - [Drawing Deep Dive](./docfx/docs/drivers.md)
+
 ## Building and Testing
 
 ### Required Tools
@@ -89,28 +96,18 @@ Welcome! This guide provides everything you need to know to contribute effective
 
 ### Common Build Issues
 
-#### Issue: Build Warnings
-- **Expected**: None warnings (~100 currently).
-- **Action**: Don't add new warnings; fix warnings in code you modify
-
 #### Issue: NativeAot/SelfContained Build
+
 - **Solution**: Restore these projects explicitly:
   ```bash
   dotnet restore ./Examples/NativeAot/NativeAot.csproj -f
   dotnet restore ./Examples/SelfContained/SelfContained.csproj -f
   ```
 
-### Running Examples
-
-**UICatalog** (comprehensive demo app):
-```bash
-dotnet run --project Examples/UICatalog/UICatalog.csproj
-```
-
----
-
 ## Coding Conventions
 
+**⚠️ CRITICAL - These rules MUST be followed in ALL new or modified code**
+
 ### Code Style Tenets
 
 1. **Six-Year-Old Reading Level** - Readability over terseness
@@ -161,8 +158,6 @@ dotnet run --project Examples/UICatalog/UICatalog.csproj
 
 **⚠️ CRITICAL - These conventions apply to ALL code - production code, test code, examples, and samples.**
 
----
-
 ## Testing Requirements
 
 ### Code Coverage
@@ -178,19 +173,17 @@ dotnet run --project Examples/UICatalog/UICatalog.csproj
 
 ### Test Patterns
 
-- **Parallelizable tests preferred** - Add new tests to `UnitTestsParallelizable` when possible
-- **Avoid static dependencies** - Don't use `Application.Init`, `ConfigurationManager` in tests
-- **Don't use `[AutoInitShutdown]`** - Legacy pattern, being phased out
 - **Make tests granular** - Each test should cover smallest area possible
 - Follow existing test patterns in respective test projects
+- **Avoid adding new tests to the `UnitTests` Project** - Make them parallelizable and add them to `UnitTests.Parallelizable`
+- **Avoid static dependencies** - DO NOT use the legacy/static `Application` API or `ConfigurationManager` in tests unless the tests explicitly test related functionality.
+- **Don't use `[AutoInitShutdown]` or `[SetupFakeApplication]`** - Legacy pattern, being phased out
 
 ### Test Configuration
 
 - `xunit.runner.json` - xUnit configuration
 - `coverlet.runsettings` - Coverage settings (OpenCover format)
 
----
-
 ## API Documentation Requirements
 
 **All public APIs MUST have XML documentation:**
@@ -202,16 +195,15 @@ dotnet run --project Examples/UICatalog/UICatalog.csproj
 - Complex topics → `docfx/docs/*.md` files
 - Proper English and grammar - Clear, concise, complete. Use imperative mood.
 
----
-
 ## Pull Request Guidelines
 
 ### PR Requirements
 
+- **ALWAYS** include instructions for pulling down locally at end of Description
+
 - **Title**: "Fixes #issue. Terse description". If multiple issues, list all, separated by commas (e.g. "Fixes #123, #456. Terse description")
 - **Description**: 
   - Include "- Fixes #issue" for each issue near the top
-  - **ALWAYS** include instructions for pulling down locally at end of Description
   - Suggest user setup a remote named `copilot` pointing to your fork
   - Example:
     ```markdown
@@ -220,99 +212,14 @@ dotnet run --project Examples/UICatalog/UICatalog.csproj
     git fetch copilot <branch-name>
     git checkout copilot/<branch-name>
     ```
-- **Coding Style**: Follow all coding conventions in this document for new and modified code
 - **Tests**: Add tests for new functionality (see [Testing Requirements](#testing-requirements))
 - **Coverage**: Maintain or increase code coverage
 - **Scenarios**: Update UICatalog scenarios when adding features
 - **Warnings**: **CRITICAL - PRs must not introduce any new warnings**
   - Any file modified in a PR that currently generates warnings **MUST** be fixed to remove those warnings
   - Exception: Warnings caused by `[Obsolete]` attributes can remain
-  - Expected baseline: ~326 warnings (mostly nullable reference warnings, unused variables, xUnit suggestions)
   - Action: Before submitting a PR, verify your changes don't add new warnings and fix any warnings in files you modify
 
----
-
-## CI/CD Workflows
-
-The repository uses multiple GitHub Actions workflows. What runs and when:
-
-### 1) Build Solution (`.github/workflows/build.yml`)
-
-- **Triggers**: push and pull_request to `v2_release`, `v2_develop` (ignores `**.md`); supports `workflow_call`
-- **Runner/timeout**: `ubuntu-latest`, 10 minutes
-- **Steps**:
-- Checkout and setup .NET 8.x GA
-- `dotnet restore`
-- Build Debug: `dotnet build --configuration Debug --no-restore -property:NoWarn=0618%3B0612`
-- Build Release (library): `dotnet build Terminal.Gui/Terminal.Gui.csproj --configuration Release --no-incremental --force -property:NoWarn=0618%3B0612`
-- Pack Release: `dotnet pack Terminal.Gui/Terminal.Gui.csproj --configuration Release --output ./local_packages -property:NoWarn=0618%3B0612`
-- Restore NativeAot/SelfContained examples, then restore solution again
-- Build Release for `Examples/NativeAot` and `Examples/SelfContained`
-- Build Release solution
-- Upload artifacts named `build-artifacts`, retention 1 day
-
-### 2) Build & Run Unit Tests (`.github/workflows/unit-tests.yml`)
-
-- **Triggers**: push and pull_request to `v2_release`, `v2_develop` (ignores `**.md`)
-- **Matrix**: Ubuntu/Windows/macOS
-- **Timeout**: 15 minutes per job
-- **Process**:
-1. Calls build workflow to build solution once
-2. Downloads build artifacts
-3. Runs `dotnet restore` (required for `--no-build` to work)
-4. **Performance optimizations**:
-   - Disables Windows Defender on Windows runners (significant speedup)
-   - Collects code coverage **only on Linux** (ubuntu-latest) for performance
-   - Windows and macOS skip coverage collection to reduce test time
-   - Increased blame-hang-timeout to 120s for Windows/macOS (60s for Linux)
-5. Runs two test jobs:
-   - **Non-parallel UnitTests**: `Tests/UnitTests` with blame/diag flags; `xunit.stopOnFail=false`
-   - **Parallel UnitTestsParallelizable**: `Tests/UnitTestsParallelizable` with blame/diag flags; `xunit.stopOnFail=false`
-6. Uploads test logs and diagnostic data from all runners
-7. **Uploads code coverage to Codecov only from Linux runner**
-
-**Test results**: All tests output to unified `TestResults/` directory at repository root
-
-### 3) Build & Run Integration Tests (`.github/workflows/integration-tests.yml`)
-
-- **Triggers**: push and pull_request to `v2_release`, `v2_develop` (ignores `**.md`)
-- **Matrix**: Ubuntu/Windows/macOS
-- **Timeout**: 15 minutes
-- **Process**:
-1. Calls build workflow
-2. Downloads build artifacts
-3. Runs `dotnet restore`
-4. **Performance optimizations** (same as unit tests):
-   - Disables Windows Defender on Windows runners
-   - Collects code coverage **only on Linux**
-   - Increased blame-hang-timeout to 120s for Windows/macOS
-5. Runs IntegrationTests with blame/diag flags; `xunit.stopOnFail=true`
-6. Uploads logs per-OS
-7. **Uploads coverage to Codecov only from Linux runner**
-
-### 4) Publish to NuGet (`.github/workflows/publish.yml`)
-
-- **Triggers**: push to `v2_release`, `v2_develop`, and tags `v*`(ignores `**.md`)
-- Uses GitVersion to compute SemVer, builds Release, packs with symbols, and pushes to NuGet.org using `NUGET_API_KEY`
-
-### 5) Build and publish API docs (`.github/workflows/api-docs.yml`)
-
-- **Triggers**: push to `v1_release` and `v2_develop`
-- Builds DocFX site on Windows and deploys to GitHub Pages when `ref_name` is `v2_release` or `v2_develop`
-
-
-### Replicating CI Locally
-
-```bash
-# Full CI sequence:
-dotnet restore
-dotnet build --configuration Debug --no-restore
-dotnet test Tests/UnitTests --no-build --verbosity normal
-dotnet test Tests/UnitTestsParallelizable --no-build --verbosity normal
-dotnet build --configuration Release --no-restore
-```
-
----
 
 ## Repository Structure
 
@@ -364,7 +271,6 @@ dotnet build --configuration Release --no-restore
 
 **`/.github/workflows/`** - CI/CD pipelines (see [CI/CD Workflows](#cicd-workflows))
 
----
 
 ## Branching Model
 
@@ -374,31 +280,6 @@ dotnet build --configuration Release --no-restore
 - `v2_release` - Stable releases, matches NuGet
 - `v1_develop`, `v1_release` - Legacy v1 (maintenance only)
 
----
-
-## Key Architecture Concepts
-
-**⚠️ CRITICAL - Contributors should understand these concepts before starting work.**
-
-See `/docfx/docs/` for deep dives on:
-
-- **Application Lifecycle** - How `Application.Init`, `Application.Run`, and `Application.Shutdown` work
-- **View Hierarchy** - Understanding `View`, `Toplevel`, `Window`, and view containment
-- **Layout System** - Pos, Dim, and automatic layout
-- **Event System** - How keyboard, mouse, and application events flow
-- **Driver Architecture** - How console drivers abstract platform differences
-- **Drawing Model** - How rendering works with Attributes, Colors, and Glyphs
-
-Key documentation:
-- [View Documentation](https://gui-cs.github.io/Terminal.Gui/docs/View.html)
-- [Events Deep Dive](https://gui-cs.github.io/Terminal.Gui/docs/events.html)
-- [Layout System](https://gui-cs.github.io/Terminal.Gui/docs/layout.html)
-- [Keyboard Handling](https://gui-cs.github.io/Terminal.Gui/docs/keyboard.html)
-- [Mouse Support](https://gui-cs.github.io/Terminal.Gui/docs/mouse.html)
-- [Drivers](https://gui-cs.github.io/Terminal.Gui/docs/drivers.html)
-
----
-
 ## What NOT to Do
 
 - ❌ Don't add new linters/formatters (use existing)
@@ -412,17 +293,4 @@ Key documentation:
 - ❌ **Don't use redundant type names with `new`** (**ALWAYS PREFER** target-typed `new ()`)
 - ❌ **Don't introduce new warnings** (fix warnings in files you modify; exception: `[Obsolete]` warnings)
 
----
-
-## Additional Resources
-
-- **Full Documentation**: https://gui-cs.github.io/Terminal.Gui
-- **API Reference**: https://gui-cs.github.io/Terminal.Gui/api/Terminal.Gui.App.html
-- **Deep Dives**: `/docfx/docs/` directory
-- **Getting Started**: https://gui-cs.github.io/Terminal.Gui/docs/getting-started.html
-- **Migrating from v1 to v2**: https://gui-cs.github.io/Terminal.Gui/docs/migratingfromv1.html
-- **Showcase**: https://gui-cs.github.io/Terminal.Gui/docs/showcase.html
-
----
-
 **Thank you for contributing to Terminal.Gui!** 🎉

Examples/CommunityToolkitExample/LoginView.cs

@@ -64,8 +64,6 @@ public void Receive (Message<LoginActions> message)
                 }
         }
         SetText ();
-        // BUGBUG: This should not be needed:
-        Application.LayoutAndDraw ();
     }
 
     private void SetText ()