gui-cs
diff --git a/‎.aider.md‎
Lines changed: 64 additions & 0 deletions b/‎.aider.md‎
Lines changed: 64 additions & 0 deletions
diff --git a/‎.cursorrules‎
Lines changed: 122 additions & 2 deletions b/‎.cursorrules‎
Lines changed: 122 additions & 2 deletions
diff --git a/‎.github/copilot-instructions.md‎
Lines changed: 32 additions & 2 deletions b/‎.github/copilot-instructions.md‎
Lines changed: 32 additions & 2 deletions
diff --git a/‎.windsurfrules‎
Lines changed: 125 additions & 0 deletions b/‎.windsurfrules‎
Lines changed: 125 additions & 0 deletions
@@ -0,0 +1,64 @@
+# Terminal.Gui - Aider AI Configuration
+
+> **Cross-platform .NET console UI toolkit. C# 14 targeting net10.0.**
+
+---
+
+## 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
+
+| 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 --no-build
+```
+
+---
+
+## 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. **No `var`** — Explicit types except built-ins (`int`, `string`, `bool`, etc.)
+3. **Use `new ()`** — `Button btn = new ()` not `Button btn = new Button ()`
+4. **Collection expressions** — Use `[...]` not `new List<T> { ... }`
+5. **SubView/SuperView** — Never "child", "parent", or "container"
+6. **Allman brace style** — Opening braces on the next line
+7. **Early return / guard clauses** — ALWAYS invert conditions and return early
+
+---
+
+## Key References
+
+For full details, see:
+- **[ai-v2-primer.md](ai-v2-primer.md)** — v1→v2 corrections and correct patterns
+- **[AGENTS.md](AGENTS.md)** — Full agent instructions with coding rules
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Human contributor guide
+- **`docfx/apispec/namespace-*.md`** — Compressed API docs
+- **`.claude/cookbook/common-patterns.md`** — Common UI recipes
@@ -1,5 +1,125 @@
 # Terminal.Gui - Cursor AI Rules
 
-> **📘 Source of Truth: [CONTRIBUTING.md](CONTRIBUTING.md)**
+> **Cross-platform .NET console UI toolkit. C# 14 targeting net10.0.**
+> Full contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md).
 
-This project uses [CONTRIBUTING.md](CONTRIBUTING.md) as the single source of truth for contribution guidelines. AI agents, including CoPilot and Cursor **MUST** follow the guidelines in [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 --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/Example/`, `Examples/UICatalog/` |
@@ -1,9 +1,36 @@
 # Terminal.Gui — Copilot Instructions
 
-Cross-platform .NET console UI toolkit. C# 12 targeting net8.0.
+Cross-platform .NET console UI toolkit. C# 14 targeting net10.0.
 Full contribution guide: [CONTRIBUTING.md](../CONTRIBUTING.md).
 Architecture deep dives: `docfx/docs/`.
 
+---
+
+## CRITICAL: Discard v1 Training Data
+
+Terminal.Gui v2 is a **complete rewrite**. Pre-2025 training data is **wrong**.
+
+> **Read [ai-v2-primer.md](../ai-v2-primer.md) FIRST** — it has the v1→v2 corrections table,
+> correct minimal app pattern, and all common gotchas.
+
+### v1 → v2 Quick Corrections
+
+| v1 (WRONG — do not use) | v2 (CORRECT) |
+|---|---|
+| `Application.Init ();` | `IApplication app = Application.Create ().Init ();` |
+| `Application.Run ();` | `app.Run<MyWindow> ();` |
+| `Application.Shutdown ();` | `app.Dispose ();` (use `using` pattern) |
+| `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 { ... }` |
+| `Application.RequestStop ()` | `App!.RequestStop ()` (from inside a `Runnable`) |
+
+---
+
 ## Build & Test
 
 Run all commands from repository root.
@@ -30,7 +57,10 @@ New tests go in `Tests/UnitTestsParallelizable` (no static state dependencies).
 
 ### Application lifecycle
 
-`Application.Init` → `Application.Run` → `Application.Shutdown`. The instance-based `IApplication` is replacing the static `Application` facade. Tests should avoid `Application.Init` unless explicitly testing that path.
+`Application.Create ()` → `.Init ()` → `.Run<T> ()` → `.Dispose ()`.
+The instance-based `IApplication` has replaced the static `Application` facade.
+Do NOT use `Application.Init()`/`Run()`/`Shutdown()`.
+Tests should avoid `Application.Init` unless explicitly testing that path.
 
 ### View system
 
 
@@ -0,0 +1,125 @@
+# 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 --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/Example/`, `Examples/UICatalog/` |