Add Markdown View (read-only) with CommonMark/GFM rendering, links, code syntax highlighting, and follow-up API/sizing fixes

.claude/POST-GENERATION-VALIDATION.md

@@ -115,7 +115,71 @@ public class MyClass
 
 **Rule:** 4 spaces per indentation level. NO tabs.
 
-## Part 2: Code Style Violations
+## Part 2: Control Flow Violations
+
+### Early Return / Guard Clauses ⚠️ COMMONLY VIOLATED
+
+```csharp
+// CORRECT ✓ — guard clause, return early
+if (view is null)
+{
+    return;
+}
+
+DoWork (view);
+
+// WRONG ✗ — happy path wrapped in conditional
+if (view is not null)
+{
+    DoWork (view);
+}
+
+// CORRECT ✓ — early return in lambda
+button.Accepting += (_, args) =>
+                    {
+                        if (_target is null)
+                        {
+                            return;
+                        }
+
+                        _target.DoWork ();
+                    };
+
+// WRONG ✗ — lambda body wrapped in conditional
+button.Accepting += (_, args) =>
+                    {
+                        if (_target is not null)
+                        {
+                            _target.DoWork ();
+                        }
+                    };
+
+// CORRECT ✓ — continue in loop
+foreach (View subView in SubViews)
+{
+    if (!subView.Visible)
+    {
+        continue;
+    }
+
+    subView.Draw ();
+}
+
+// WRONG ✗ — loop body wrapped in conditional
+foreach (View subView in SubViews)
+{
+    if (subView.Visible)
+    {
+        subView.Draw ();
+    }
+}
+```
+
+**Scan pattern:** Look for `if (condition) { ... } return` — the `if` block likely wraps happy-path code and should be inverted into a guard clause.
+
+**Rule:** ALWAYS invert conditions and return/continue early. NEVER wrap the happy path in a conditional. See `.claude/rules/early-return.md` for full guidance.
+
+## Part 3: Code Style Violations
 
 ### No `var` for Non-Built-In Types
 ```csharp

.claude/REFRESH.md

@@ -14,6 +14,7 @@
 8. **SPACE BEFORE PARENTHESES** - `Method ()` not `Method()`, `array [i]` not `array[i]` (see `formatting.md`)
 9. **Braces on next line** - ALL opening braces on next line (Allman style)
 10. **Blank lines** - before `return`/`break`/`continue`/`throw`, after control blocks
+11. **Early return / guard clauses** - ALWAYS invert conditions and return/continue early. NEVER wrap the happy path in a conditional. This applies in methods, lambdas, loops — everywhere. (see `early-return.md`)
 
 ## Before Each File Edit
 
@@ -26,6 +27,7 @@ Ask yourself:
 - [ ] **Did I add space BEFORE parentheses and brackets?**
 - [ ] **Are ALL braces on the next line?**
 - [ ] **Did I add blank lines before returns and after control blocks?**
+- [ ] **Am I using guard clauses / early return instead of nesting?**
 
 ## If Unsure
 

.claude/rules/early-return.md

@@ -0,0 +1,70 @@
+# Early Return / Guard Clauses
+
+**Invert conditions, return/continue early, keep happy path at lowest indentation. Applies everywhere: methods, lambdas, loops.**
+
+## ✅ Do / ❌ Don't
+
+```csharp
+// ✅ Guard clause
+if (view is null) { return; }
+DoWork (view);
+
+// ❌ Wrapped happy path
+if (view is not null) { DoWork (view); }
+```
+
+```csharp
+// ✅ Sequential guards in lambda
+button.Accepting += (_, args) =>
+                    {
+                        if (_target is null) { return; }
+                        if (args.Cancel) { return; }
+                        _target.DoWork ();
+                    };
+
+// ❌ Compound condition wrapping lambda body
+button.Accepting += (_, args) =>
+                    {
+                        if (_target is not null && !args.Cancel)
+                        {
+                            _target.DoWork ();
+                        }
+                    };
+```
+
+```csharp
+// ✅ Continue in loops
+foreach (View subView in SubViews)
+{
+    if (!subView.Visible) { continue; }
+    subView.Draw ();
+}
+
+// ❌ Loop body inside conditional
+foreach (View subView in SubViews)
+{
+    if (subView.Visible) { subView.Draw (); }
+}
+```
+
+```csharp
+// ✅ Guard early before tail work
+int total = widths.Sum ();
+if (total <= available) { return widths; }
+int excess = total - available;
+ReduceEvenly (widths, minWidths, excess);
+return widths;
+
+// ❌ Tail work wrapped in conditional
+int total = widths.Sum ();
+if (total > available)
+{
+    int excess = total - available;
+    ReduceEvenly (widths, minWidths, excess);
+}
+return widths;
+```
+
+## Key Principle
+
+When adding a null check or validation, **add a guard at the top** — don't indent existing code into a new `if` block. Compound conditions are fine in guard clauses (`if (x <= 0 || y <= 0) { return; }`) but never for wrapping the happy path.

AGENTS.md

@@ -88,9 +88,8 @@ dotnet test --project Tests/UnitTestsParallelizable --no-build --filter-method "
 5. **Unused lambda params** - Use `_` discard: `(_, _) => { }`
 6. **Local functions** - Use PascalCase: `void MyLocalFunc ()`
 7. **Backing fields** - Place immediately before their property
-8. **Early return** - Prefer guard clauses over nested `if`/`else`
+8. **Early return / guard clauses (CRITICAL)** - ALWAYS prefer guard clauses over nested `if`/`else`. Invert the condition, return/continue early, keep happy path at lowest indentation. This applies to methods, lambdas, loops — everywhere. See [early-return.md](/.claude/rules/early-return.md) for detailed examples.
 9. **One type per file** - Public and internal types each get their own file
-10. **Prefer early exit `if`** - Reduce nesting and return early when using `if`
 
 ## Detailed Coding Rules
 
@@ -101,6 +100,7 @@ Consult these files in `.claude/rules/` before editing code:
 - [Collection Expressions](/.claude/rules/collection-expressions.md) - `[...]` syntax
 - [Terminology](/.claude/rules/terminology.md) - SubView/SuperView terms
 - [Event Patterns](/.claude/rules/event-patterns.md) - Lambdas, handlers, closures
+- [Early Return](/.claude/rules/early-return.md) - **Guard clauses, minimal nesting** (commonly violated!)
 - [CWP Pattern](/.claude/rules/cwp-pattern.md) - Cancellable Workflow Pattern
 - [Code Layout](/.claude/rules/code-layout.md) - Member ordering, backing fields
 - [Testing Patterns](/.claude/rules/testing-patterns.md) - Test writing conventions

CLAUDE.md

@@ -45,6 +45,7 @@ See `.claude/rules/` for detailed guidance:
 - `target-typed-new.md` - Use `new ()` not `new TypeName()`
 - `terminology.md` - **SubView/SuperView**, never "child/parent"
 - `event-patterns.md` - Lambdas, closures, handlers
+- `early-return.md` - **Guard clauses, minimal nesting** (commonly violated!)
 - `collection-expressions.md` - Use `[...]` syntax
 - `cwp-pattern.md` - Cancellable Workflow Pattern
 - `code-layout.md` - Backing fields, member ordering
@@ -105,7 +106,7 @@ dotnet test --project Tests/UnitTests --no-build
 6. **Use `[...]`** not `new () { ... }` for collections
 7. **SubView/SuperView** for containment (Parent/Child only for non-containment refs)
 8. **Unused lambda params** - use `_`: `(_, _) => { }`
-9. **Early return** - Prefer guard clauses over nested `if`/`else`
+9. **Early return / guard clauses** - ALWAYS invert conditions and return/continue early. Never wrap the happy path in a conditional. Applies to methods, lambdas, and loops. See `.claude/rules/early-return.md`.
 10. **One type per file** - Public and internal types each get their own file
 
 ## Testing
@@ -133,6 +134,7 @@ dotnet test --project Tests/UnitTests --no-build
 - Don't use `var` for non-built-in types
 - Don't use redundant type names with `new`
 - Don't say "child/parent" for containment (use SubView/SuperView)
+- Don't wrap the happy path in a conditional — use guard clauses and return early
 - Don't modify unrelated code
 - Don't introduce new warnings
 - Don't skip POST-GENERATION-VALIDATION.md after writing code

Directory.Packages.props

@@ -19,6 +19,7 @@
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.5" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.5" />
     <PackageVersion Include="System.IO.Abstractions" Version="22.1.1" />
+    <PackageVersion Include="TextMateSharp" Version="2.0.3" />
     <PackageVersion Include="Wcwidth" Version="4.0.1" />
     <PackageVersion Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.23.0" />
     <PackageVersion Include="Serilog" Version="4.3.1" />
@@ -37,6 +38,8 @@
     <PackageVersion Include="ReactiveUI.SourceGenerators" Version="2.6.1" />
     <PackageVersion Include="GitHub.Copilot.SDK" Version="0.2.2" />
     <PackageVersion Include="Moq" Version="4.20.72" />
+    <PackageVersion Include="Markdig" Version="0.39.0" />
+    <PackageVersion Include="TextMateSharp.Grammars" Version="2.0.3" />
     <PackageVersion Include="ReportGenerator" Version="5.5.4" />
     <PackageVersion Include="TestableIO.System.IO.Abstractions.TestingHelpers" Version="22.1.1" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.4.0" />

Examples/AI/ChatView.cs

@@ -1,3 +1,4 @@
+using System.Text;
 using GitHub.Copilot.SDK;
 using Terminal.Gui.App;
 using Terminal.Gui.Drawing;
@@ -15,7 +16,8 @@ internal sealed class ChatView : Window
     private readonly IApplication _app;
     private readonly CopilotClient _client;
     private string _model;
-    private readonly TextView _conversationView;
+    private readonly Markdown _conversationView;
+    private readonly StringBuilder _conversationText = new ();
     private readonly TextField _inputField;
     private readonly View _inputIndicator;
     private readonly SpinnerView _spinner;
@@ -47,32 +49,17 @@ public ChatView (IApplication app, CopilotClient client, string model)
             Width = 5,
             Visible = false
         };
-        var spinnerShortcut = new Shortcut { CommandView = _spinner, MouseHighlightStates = MouseState.None, Enabled = false };
+        Shortcut spinnerShortcut = new () { CommandView = _spinner, MouseHighlightStates = MouseState.None, Enabled = false };
         Shortcut quitShortcut = new (Application.GetDefaultKey (Command.Quit), "Quit", RequestStop);
 
         _statusBar = new StatusBar { AlignmentModes = AlignmentModes.IgnoreFirstOrLast, SchemeName = SchemeName, BorderStyle = LineStyle.None };
         _statusBar.Add (spinnerShortcut, quitShortcut);
 
-        _conversationView = new TextView
+        _conversationView = new Markdown
         {
-            Width = Dim.Fill (),
-            Height = Dim.Auto (minimumContentDim: 1, maximumContentDim: Dim.Func (_ => GetMaxConversationHeight ())),
-            ReadOnly = true,
-            WordWrap = true
+            Width = Dim.Fill (), Height = Dim.Auto (minimumContentDim: 1, maximumContentDim: Dim.Func (_ => GetMaxConversationHeight ()))
         };
 
-        _conversationView.GettingAttributeForRole += (sender, args) =>
-                                                     {
-                                                         var view = sender as View;
-
-                                                         if (args.Role != VisualRole.ReadOnly)
-                                                         {
-                                                             return;
-                                                         }
-                                                         args.Result = view?.GetAttributeForRole (VisualRole.Normal);
-                                                         args.Handled = true;
-                                                     };
-
         _inputIndicator = new View
         {
             Text = $"{Glyphs.RightArrow}",
@@ -88,7 +75,7 @@ public ChatView (IApplication app, CopilotClient client, string model)
         _inputField.Border.LineStyle = _inputIndicator.Border.LineStyle;
         _inputField.Border.Thickness = new Thickness (0, 1, 0, 1);
 
-        _inputField.Autocomplete.SuggestionGenerator = new SlashCommandSuggestionGenerator ();
+        _inputField.Autocomplete?.SuggestionGenerator = new SlashCommandSuggestionGenerator ();
         _inputField.Accepted += OnInputAccepted;
 
         Add (_conversationView, _inputIndicator, _inputField, _statusBar);
@@ -222,8 +209,8 @@ private async Task ValidateAndSwitchModel (string newModel)
 
     private void AppendToConversation (string text)
     {
-        _conversationView.Text += text;
-        _conversationView.MoveEnd ();
+        _conversationText.Append (text);
+        _conversationView.Text = _conversationText.ToString ();
     }
 
     private void HandleSlashCommand (string command)
@@ -239,6 +226,7 @@ private void HandleSlashCommand (string command)
                 break;
 
             case "clear":
+                _conversationText.Clear ();
                 _conversationView.Text = string.Empty;
                 AppendToConversation ($"{Glyphs.Diamond} Conversation cleared.\n");
 

Examples/AI/SingleTurnView.cs

@@ -16,7 +16,7 @@ internal sealed class SingleTurnView : Window
     private readonly CopilotClient _client;
     private readonly string _model;
     private readonly string _prompt;
-    private readonly Label _responseLabel;
+    private readonly Markdown _responseView;
 
     public SingleTurnView (IApplication app, CopilotClient client, string model, string prompt)
     {
@@ -30,9 +30,9 @@ public SingleTurnView (IApplication app, CopilotClient client, string model, str
         Height = Dim.Auto ();
         Border.LineStyle = LineStyle.Rounded;
 
-        _responseLabel = new Label { Width = Dim.Fill (), Height = Dim.Auto () };
+        _responseView = new Markdown { Width = Dim.Fill (), Height = Dim.Auto () };
 
-        Add (_responseLabel);
+        Add (_responseView);
     }
 
     /// <inheritdoc/>
@@ -67,7 +67,7 @@ private async Task streamResponse ()
                                 case AssistantMessageDeltaEvent delta:
                                     responseText.Append (delta.Data.DeltaContent);
 
-                                    _app.Invoke (() => { _responseLabel.Text = responseText.ToString (); });
+                                    _app.Invoke (() => { _responseView.Text = responseText.ToString (); });
 
                                     break;
 
@@ -77,7 +77,7 @@ private async Task streamResponse ()
                                     break;
 
                                 case SessionErrorEvent err:
-                                    _app.Invoke (() => { _responseLabel.Text = $"Error: {err.Data.Message}"; });
+                                    _app.Invoke (() => { _responseView.Text = $"Error: {err.Data.Message}"; });
                                     done.TrySetResult ();
 
                                     break;
@@ -89,7 +89,7 @@ private async Task streamResponse ()
         }
         catch (Exception ex)
         {
-            _app.Invoke (() => _responseLabel.Text = $"Error: {ex.Message}");
+            _app.Invoke (() => _responseView.Text = $"Error: {ex.Message}");
         }
 
         // Give the UI a moment to render the final update, then exit