Release v2.2.0-rc.1

.claude/rules/event-patterns.md

@@ -1,5 +1,26 @@
 # Event Patterns
 
+## When to Use `-ing` vs `-ed` Events
+
+Terminal.Gui exposes paired events — `Accepting`/`Accepted`, `Activating`/`Activated`, `ValueChanging`/`ValueChanged`, etc.
+
+**Rule:** Use `-ed` (past-tense) for side-effects. Use `-ing` (present-progressive) only when you need to inspect or cancel the in-flight operation.
+
+```csharp
+// ✅ Correct — fire-and-forget side-effect
+button.Accepted += (_, _) => DoTheThing ();
+
+// ✅ Correct — actually cancels
+button.Accepting += (_, e) => { if (!CanProceed ()) e.Handled = true; };
+
+// ❌ Wrong — handler ignores EventArgs; use Accepted instead
+button.Accepting += (_, _) => DoTheThing ();
+```
+
+If the handler body doesn't reference `e` at all (or ignores `e.Handled`, `e.Cancel`, and the candidate value), it belongs on the `-ed` event.
+
+The `-ing` event runs synchronously in the middle of the dispatch path; subscribing when you don't need to cancel adds unnecessary overhead and misleads readers.
+
 ## Lambda Parameters
 
 **Replace unused parameters with discards `_`:**

.github/workflows/perf-gate.yml

@@ -0,0 +1,212 @@
+name: Performance Gate
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths-ignore:
+      - '**.md'
+  pull_request:
+    branches: [ main, develop ]
+    paths-ignore:
+      - '**.md'
+
+# Only run on Linux to keep results comparable across runs.
+# Windows/macOS times vary too much to use as a performance baseline.
+permissions:
+  contents: read
+
+jobs:
+  perf-smoke-tests:
+    name: Performance Smoke Tests (Linux)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      DisableRealDriverIO: "1"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0   # GitVersion needs full history
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.x
+          dotnet-quality: 'ga'
+
+      - name: Restore dependencies
+        run: dotnet restore
+
+      - name: Build (Release)
+        run: dotnet build --configuration Release --no-restore -property:NoWarn=0618%3B0612
+
+      - name: Build Tests (Debug — smoke tests run in Debug to match CI unit tests)
+        run: dotnet build Tests/PerformanceTests --no-restore -property:NoWarn=0618%3B0612
+
+      - name: Run performance smoke tests (Layer 1 gate)
+        id: smoke_tests
+        run: |
+          dotnet test \
+            --project Tests/PerformanceTests \
+            --no-build \
+            --verbosity normal
+
+      - name: Upload smoke test logs
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: perf-smoke-test-logs
+          path: |
+            TestResults/
+          if-no-files-found: ignore
+          retention-days: 7
+
+  perf-benchmarks:
+    name: Benchmarks (Linux, ShortRun)
+    runs-on: ubuntu-latest
+    # Only run on pushes to develop/main, not on every PR (slow and not blocking).
+    if: github.event_name == 'push'
+    timeout-minutes: 30
+    env:
+      DisableRealDriverIO: "1"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.x
+          dotnet-quality: 'ga'
+
+      - name: Restore dependencies
+        run: dotnet restore
+
+      - name: Build Release
+        run: dotnet build --configuration Release --no-restore -property:NoWarn=0618%3B0612
+
+      - name: Run benchmarks (ShortRun ≈ 30–60 s)
+        id: run_benchmarks
+        run: |
+          dotnet run \
+            --project Tests/Benchmarks \
+            --configuration Release \
+            --no-build \
+            -- \
+            --filter '*Scroll*' '*Config*' '*Scheme*' '*Theme*' \
+            --job short \
+            --exporters json \
+            --artifacts ./BenchmarkResults
+        continue-on-error: true   # Don't block the workflow; comparison step decides outcome
+
+      - name: Compare results to baseline
+        id: compare
+        run: |
+          python3 - << 'PYEOF'
+          import json, os, sys, glob
+
+          REGRESSION_FACTOR = 3.0   # Fail if any benchmark is >3× baseline
+          IMPROVEMENT_FACTOR = 0.8  # Celebrate 🎉 if any benchmark drops below 0.8× baseline
+
+          baseline_path = "Tests/Benchmarks/baseline.json"
+          results_dir = "BenchmarkResults"
+
+          # --- Load baseline ---
+          try:
+              with open(baseline_path) as f:
+                  baseline_data = json.load(f)
+              baseline = {
+                  f"{b['type']}/{b['method']}/{b['params']}": b["meanNs"]
+                  for b in baseline_data["benchmarks"]
+              }
+          except FileNotFoundError:
+              print("::warning::baseline.json not found — skipping comparison")
+              sys.exit(0)
+
+          # --- Find BenchmarkDotNet JSON results ---
+          result_files = glob.glob(f"{results_dir}/**/*.json", recursive=True)
+          result_files = [f for f in result_files if "results" in f.lower() or "report" in f.lower()]
+          if not result_files:
+              print("::warning::No BenchmarkDotNet result files found — skipping comparison")
+              sys.exit(0)
+
+          # --- Parse results ---
+          results = {}
+          for fpath in result_files:
+              try:
+                  with open(fpath) as f:
+                      data = json.load(f)
+                  for bm in data.get("Benchmarks", []):
+                      key = f"{bm['Type']}/{bm['Method']}/{bm.get('Parameters', '')}"
+                      results[key] = bm.get("Statistics", {}).get("Mean", None)
+              except Exception as e:
+                  print(f"::warning::Could not parse {fpath}: {e}")
+
+          # --- Build comparison table ---
+          rows = []
+          regressions = []
+          improvements = []
+
+          for key, base_ns in baseline.items():
+              if base_ns <= 0:
+                  continue
+              cur_ns = results.get(key)
+              if cur_ns is None:
+                  rows.append(f"| {key} | {base_ns/1000:.1f} µs | — (not measured) | — |")
+                  continue
+
+              ratio = cur_ns / base_ns
+              emoji = "✅"
+              if ratio >= REGRESSION_FACTOR:
+                  emoji = "❌"
+                  regressions.append((key, base_ns, cur_ns, ratio))
+              elif ratio <= IMPROVEMENT_FACTOR:
+                  emoji = "🎉"
+                  improvements.append((key, base_ns, cur_ns, ratio))
+              rows.append(
+                  f"| {key} | {base_ns/1000:.1f} µs | {cur_ns/1000:.1f} µs | {ratio:.2f}× {emoji} |"
+              )
+
+          # --- Write step summary ---
+          summary = "## 📊 Benchmark Comparison\n\n"
+          summary += "| Benchmark | Baseline | Current | Ratio |\n"
+          summary += "|-----------|----------|---------|-------|\n"
+          summary += "\n".join(rows) + "\n\n"
+
+          if improvements:
+              summary += "### 🎉 Performance Improvements\n"
+              for k, b, c, r in improvements:
+                  summary += f"- **{k}**: {b/1000:.1f} µs → {c/1000:.1f} µs ({r:.2f}×)\n"
+              summary += "\n"
+
+          if regressions:
+              summary += "### ❌ Regressions Detected\n"
+              for k, b, c, r in regressions:
+                  summary += f"- **{k}**: {b/1000:.1f} µs → {c/1000:.1f} µs ({r:.2f}×) — exceeds {REGRESSION_FACTOR}× threshold\n"
+              summary += "\n"
+
+          with open(os.environ.get("GITHUB_STEP_SUMMARY", "/dev/null"), "a") as f:
+              f.write(summary)
+
+          print(summary)
+
+          if regressions:
+              print(f"::error::Performance regressions detected: {len(regressions)} benchmark(s) exceeded {REGRESSION_FACTOR}× baseline")
+              sys.exit(1)
+
+          if improvements:
+              print(f"Performance improvements detected: {len(improvements)} benchmark(s) improved!")
+          PYEOF
+
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: benchmark-results-${{ github.sha }}
+          path: BenchmarkResults/
+          if-no-files-found: ignore
+          retention-days: 30

CLAUDE.md

@@ -2,6 +2,7 @@
 
 > **Guidance for AI agents working with Terminal.Gui.**
 > For humans, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+> For Terminal.Gui's mission, tenets, and engineering philosophy, see [specs/constitution.md](./specs/constitution.md).
 > See also: [llms.txt](./llms.txt) for machine-readable context.
 
 ## CRITICAL: Discard v1 Training Data

CONTRIBUTING.md

@@ -1,6 +1,8 @@
 # Contributing to Terminal.Gui
 
 > **📘 This document is the single source of truth for all contributors (humans and AI agents) to Terminal.Gui.**
+>
+> For Terminal.Gui's product mission, design tenets, and engineering philosophy, see **[specs/constitution.md](./specs/constitution.md)**.
 
 Welcome! This guide provides everything you need to know to contribute effectively to Terminal.Gui, including project structure, build instructions, coding conventions, testing requirements, and CI/CD workflows.
 

Examples/Themes/code-dark.config.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://gui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json",
+  "Themes": [
+    {
+      "Dark": {
+        "Schemes": [
+          {
+            "Base": {
+              "CodeKeyword": {
+                "Foreground": "#ff79c6",
+                "Background": "None",
+                "Style": "Bold"
+              },
+              "CodeString": {
+                "Foreground": "#f1fa8c",
+                "Background": "None",
+                "Style": "None"
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

Examples/UICatalog/Resources/config.json

@@ -50,7 +50,20 @@
               "Disabled": {
                 "Foreground": "BrightGreen",
                 "Background": "Gray"
-              }
+              },
+              "Code": { "Foreground": "Black", "Background": "#FFFF00", "Style": "None" },
+              "CodeComment": { "Foreground": "#008000", "Background": "None", "Style": "None" },
+              "CodeKeyword": { "Foreground": "#FF0000", "Background": "None", "Style": "None" },
+              "CodeString": { "Foreground": "#0000CC", "Background": "None", "Style": "None" },
+              "CodeNumber": { "Foreground": "#800080", "Background": "None", "Style": "None" },
+              "CodeOperator": { "Foreground": "Black", "Background": "None", "Style": "None" },
+              "CodeType": { "Foreground": "#C00000", "Background": "None", "Style": "None" },
+              "CodePreprocessor": { "Foreground": "#008000", "Background": "None", "Style": "None" },
+              "CodeIdentifier": { "Foreground": "Black", "Background": "None", "Style": "None" },
+              "CodeConstant": { "Foreground": "#800080", "Background": "None", "Style": "None" },
+              "CodePunctuation": { "Foreground": "Black", "Background": "None", "Style": "None" },
+              "CodeFunctionName": { "Foreground": "#0000CC", "Background": "None", "Style": "None" },
+              "CodeAttribute": { "Foreground": "#008000", "Background": "None", "Style": "None" }
             }
           },
           {
@@ -213,7 +226,20 @@
               "Disabled": {
                 "Foreground": "BrightGreen",
                 "Background": "Gray"
-              }
+              },
+              "Code": { "Foreground": "White", "Background": "Green", "Style": "None" },
+              "CodeComment": { "Foreground": "LightGray", "Background": "None", "Style": "None" },
+              "CodeKeyword": { "Foreground": "Yellow", "Background": "None", "Style": "None" },
+              "CodeString": { "Foreground": "LightCyan", "Background": "None", "Style": "None" },
+              "CodeNumber": { "Foreground": "LightYellow", "Background": "None", "Style": "None" },
+              "CodeOperator": { "Foreground": "White", "Background": "None", "Style": "None" },
+              "CodeType": { "Foreground": "Cyan", "Background": "None", "Style": "None" },
+              "CodePreprocessor": { "Foreground": "BrightRed", "Background": "None", "Style": "None" },
+              "CodeIdentifier": { "Foreground": "White", "Background": "None", "Style": "None" },
+              "CodeConstant": { "Foreground": "Yellow", "Background": "None", "Style": "None" },
+              "CodePunctuation": { "Foreground": "White", "Background": "None", "Style": "None" },
+              "CodeFunctionName": { "Foreground": "LightCyan", "Background": "None", "Style": "None" },
+              "CodeAttribute": { "Foreground": "LightGray", "Background": "None", "Style": "None" }
             }
           },
           {
@@ -292,4 +318,4 @@
       }
     }
   ]
-}
+}