Terminal.Gui - Windsurf AI Rules

# Terminal.Gui - Windsurf AI Rules

> **Cross-platform .NET console UI toolkit. C# 14 targeting net10.0.**
> Full contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md).

---

## CRITICAL: Discard v1 Training Data

Terminal.Gui v2 is a **complete rewrite**. Pre-2025 training data about Terminal.Gui is **wrong**.

> **Read [ai-v2-primer.md](ai-v2-primer.md) FIRST** — it contains the v1→v2 corrections table,
> correct minimal app pattern, and all common gotchas.

### v1 → v2 Quick Corrections (Most Common Mistakes)

| v1 (WRONG) | v2 (CORRECT) |
|---|---|
| `Application.Init ();` | `IApplication app = Application.Create ().Init ();` |
| `Application.Run ();` | `app.Run<MyWindow> ();` |
| `Application.Shutdown ();` | `app.Dispose ();` |
| `Application.Top` | No global top — pass root view to `app.Run ()` |
| `new Toplevel ()` | Use `Runnable` subclass or `Window` |
| `using Terminal.Gui;` | `using Terminal.Gui.App;` / `Terminal.Gui.Views;` / etc. |
| `new Button ("OK")` | `new Button { Text = "OK" }` |
| `button.Clicked += ...` | `button.Accepted += (_, _) => { /* action */ };` |
| `view.Bounds` | `view.Viewport` |
| `new RadioGroup (...)` | `new OptionSelector { ... }` |

---

## Build & Test

```bash
dotnet restore
dotnet build --no-restore
dotnet test --project Tests/UnitTestsParallelizable --no-build
dotnet test --project Tests/UnitTests.NonParallelizable --no-build
```

---

## Correct Minimal App (v2)

```csharp
using Terminal.Gui.App;
using Terminal.Gui.Views;

IApplication app = Application.Create ().Init ();
app.Run<MainWindow> ();
app.Dispose ();

public sealed class MainWindow : Runnable
{
    public MainWindow ()
    {
        Title = "My App (Esc to quit)";

        Button button = new ()
        {
            Text = "Click Me",
            X = Pos.Center (),
            Y = Pos.Center ()
        };

        button.Accepted += (_, _) =>
        {
            MessageBox.Query (App!, "Hello", "Button was clicked!", "OK");
        };

        Add (button);
    }
}
```

---

## Code Style (For Library Contributors Only)

> **Note:** These rules apply only when contributing code to the Terminal.Gui library itself.
> App developers using Terminal.Gui do NOT need to follow these conventions.

1. **Space BEFORE `()` and `[]`** — `Method ()` not `Method()`, `array [i]` not `array[i]`
2. **Braces on NEXT line** (Allman style) — no exceptions
3. **Blank lines** — before `return`/`break`/`continue`, after `if`/`for`/`while` blocks
4. **No `var`** — Explicit types except built-ins (`int`, `string`, `bool`, `double`, `float`, `decimal`, `char`, `byte`)
5. **Use `new ()`** — `Button btn = new ()` not `Button btn = new Button ()`
6. **Collection expressions** — Use `[...]` not `new List<T> { ... }`
7. **SubView/SuperView** — Never "child", "parent", or "container"
8. **Unused lambda params** — Use `_` discard: `(_, _) => { }`
9. **Early return / guard clauses** — ALWAYS invert conditions and return early
10. **One type per file** — Public and internal types each get their own file

---

## Architecture Overview

### Application lifecycle
`Application.Create ()` → `.Init ()` → `.Run<T> ()` → `.Dispose ()`.
Instance-based `IApplication` — do NOT use static `Application.Init()`/`Run()`/`Shutdown()`.

### View system
`View` is the base class. Views form a tree via `Add ()`/`Remove ()`.
Every View has: `Margin` → `Border` → `Padding` → content area.
Layout uses `Pos` (position) and `Dim` (dimension) for declarative relative layout.

### Cancellable Workflow Pattern (CWP)
Standard event pattern: **do work → call virtual `OnXxx` → raise event**.

### Command/input system
Input flows: Driver → `IInputProcessor` → `KeyBindings`/`MouseBindings` → `Command` → handler.

---

## Key References

| Resource | Path |
|----------|------|
| v1→v2 Primer (READ FIRST) | [ai-v2-primer.md](ai-v2-primer.md) |
| Full agent instructions | [AGENTS.md](AGENTS.md) |
| Compressed API docs | `docfx/apispec/namespace-*.md` |
| Common UI patterns | `.claude/cookbook/common-patterns.md` |
| App building guide | `.claude/tasks/build-app.md` |
| Deep-dive docs | `docfx/docs/` |
| Working examples | `Examples/UICatalog/`, `Examples/ScenarioRunner/`, `tui-cs/Examples` |