Terminal.Gui/AGENTS.md

Terminal.Gui - GitHub Copilot Instructions

This file provides instructions for GitHub Copilot when working with the Terminal.Gui project.

Project Overview

Terminal.Gui is a cross-platform UI toolkit for creating console-based graphical user interfaces in .NET. It provides a comprehensive framework for building interactive console applications with support for keyboard and mouse input, customizable views, and a robust event system. The toolkit works across Windows, macOS, and Linux, leveraging platform-specific console capabilities where available.

Key characteristics:

• Cross-platform terminal/console UI framework for .NET
• Supports Windows, macOS, and Linux
• Rich GUI controls (buttons, dialogs, menus, text boxes, etc.)
• Keyboard-first design with full mouse support
• Follows Microsoft .NET Framework Design Guidelines, with some tweaks.
• v2 is currently in Alpha with stable core API (v1 is in maintenance mode)

Documentation

• Full documentation: gui-cs.github.io/Terminal.Gui
• API Reference: API Documentation
• Getting Started: Getting Started Guide

Repository Structure

• /Terminal.Gui/ - Core library source code
  • App/ - Core application logic, Application.cs (static class managing RunState and MainLoop)
  • Configuration/ - ConfigurationManager for application settings
  • Drivers/ - Console driver implementations (IConsoleDriver.cs, NetDriver, UnixDriver, WindowsDriver)
  • Drawing/ - Rendering graphical elements in the console
  • Input/ - Keyboard and mouse input handling
  • View/ - Core View class hierarchy
  • Views/ - Specific sub-classes of View (Toplevel, Window, Dialog, etc.)
• /Examples/ - Sample applications and demos
• /Examples/UICatalog/ - Comprehensive demo app for manual testing
• /Tests/ - Unit and integration tests
• /docfx/ - Documentation source files (Deep Dive Articles and API docs)
• /Scripts/ - Build and utility scripts

Branching Model

Terminal.Gui uses GitFlow:

• v2_develop - Default branch for v2 development (active development)
• v2_release - Stable release branches matching NuGet packages

Code Style and Standards

Code Style Tenets

1. Six-Year-Old Reading Level - Prioritize readability over terseness. Use clear variable names and comments.
2. Consistency, Consistency, Consistency - Follow established patterns ruthlessly.
3. Don't be Weird - Follow Microsoft and .NET community conventions.
4. Set and Forget - Use ReSharper/Rider for automated formatting.
5. Documentation is the Spec - API documentation is the source of truth.

Coding Conventions

• Based on Microsoft C# Coding Conventions
• Project settings defined and enforced via ./Terminal.sln.DotSettings and ./.editorconfig
• Use var only for the most basic dotnet types - prefer explicit types for clarity
• Use target-typed new

API Design Guidelines

Public API Tenets

1. Stand on the shoulders of giants - Follow Microsoft .NET Framework Design Guidelines
2. Don't Break Existing Stuff - Avoid breaking changes; find compatible ways to add features
3. Fail-fast - Prefer early failure to expose bugs sooner
4. Standards Reduce Complexity - Use standard .NET idioms, tweaked to match Terminal.Gui.

API Documentation Requirements

All public APIs must have XML documentation:

• Clear, concise, and complete <summary> tags
• Use <see cref=""/> liberally for cross-references
• Add <remarks> for context and detailed explanations
• Document complex topics in docfx/articles/*.md files
• Use proper English and correct grammar
• Provide sample code via <example> in cases where a sample is needed (not for very obvious things)

Events

• Follow the Events Deep Dive documentation
• Use the Cancellable Work Pattern for user-initiated actions
• Use the CWPHelpers if possible
• Name event handlers consistently (e.g., On[EventName]), following dotnet guidelines.

User Experience Tenets

1. Honor What's Come Before - Follow established Mac/Windows GUI idioms (e.g., Ctrl-C for copy)
2. Consistency Matters - Common UI patterns should be consistent (e.g., Ctrl-Q quits modals)
3. Honor the OS, but Work Everywhere - Take advantage of platform capabilities while maintaining cross-platform support
4. Keyboard first, Mouse also - Optimize for keyboard, but ensure everything also works with mouse

Testing

Unit Test Requirements

• Never decrease code coverage - Aim for 70%+ coverage on new code
• Write unit tests for all new functionality
• Follow existing test patterns in /Tests/
• Many existing unit tests are obtuse and not really unit tests. Anytime new tests are added or updated, strive to refactor the tests into more granular tests where each test covers the smallest area possible.
• Many existing unit tests in the ./Tests/UnitTests project incorrectly require Application.Init and use [AutoInitShutdown]. Anytime new tests are added or updated, strive to remove these dependencies and make the tests parallelizable. This means not taking any dependency on static objects like Application and ConfigurationManager.

Pull Request Guidelines

• Titles should be of the form "Fixes #issue. Terse description."
• If the PR addresses multiple issues, use "Fixes #issue1, #issue2. Terse description."
• First comment should include "- Fixes #issue" for each issue addressed. If an issue is only partially addressed, use "Partially addresses #issue".
• First comment should include a thorough description of the change and any impact.
• Put temporary .md files in /docfx/docs/drafts/ and remove before merging.

Building and Running

Build the Solution

dotnet build

Run Tests

dotnet test

Key Concepts

./docfx/docs contains a set of architectural and key-concept deep-dives.

Additional Guidelines

1. Maintain existing code structure and organization unless explicitly told
2. View sub-classes must not use private APIs
3. Suggest changes to the ./docfx/docs/ folder when appropriate

Working with Pull Request Branches

When creating PRs, include instructions at the end of each PR description for how to pull the branch down locally. Use the following template, adapted for the typical remote setup where origin points to the user's fork and upstream points to gui-cs/Terminal.Gui:

## How to Pull This PR Branch Locally

If you want to test or modify this PR locally, use one of these approaches based on your remote setup:

### Method 1: Fetch from upstream (if branch exists there)
```bash
# Fetch the branch from upstream
git fetch upstream <branch-name>

# Switch to the branch
git checkout <branch-name>

# Make your changes, then commit them
git add .
git commit -m "Your commit message"

# Push to your fork (origin)
git push origin <branch-name>

Method 2: Fetch by PR number

# Fetch the PR branch from upstream by PR number
git fetch upstream pull/<PR_NUMBER>/head:<branch-name>

# Switch to the branch
git checkout <branch-name>

# Make your changes, then commit them
git add .
git commit -m "Your commit message"

# Push to your fork (origin)
git push origin <branch-name>

The PR will automatically update when you push to the branch in your fork.

**Note:** Adjust the remote names if your setup differs (e.g., if `origin` points to `gui-cs/Terminal.Gui` and you have a separate remote for your fork).