AI Coding Agent Guidelines for Hex1b

This document provides context and conventions for AI coding agents (GitHub Copilot, Claude, Cursor, etc.) working with the Hex1b codebase.

🛠️ Available Skills

This repository includes specialized skills in .github/skills/ that provide detailed guidance for specific tasks. Invoke these skills when working on related tasks - they contain step-by-step procedures, templates, and best practices.

Skills are invoked automatically by AI agents based on the task context. They contain comprehensive procedures that complement the high-level guidance in this file.

📋 Project Overview

Hex1b is a .NET library for building terminal user interfaces (TUI) with a React-inspired declarative API. The library ships to NuGet as Hex1b.

Key Technologies

• .NET 10.0 (preview) - Target framework
• C# 12+ - Modern C# features enabled
• MSTest (MSTest.Sdk 4.x with Microsoft.Testing.Platform) - Testing framework
• .NET Aspire - Used for running sample applications

Repository Layout

src/Hex1b/           → Main library (THE shipped package)
tests/Hex1b.Tests/   → Unit tests
samples/             → Example applications
apphost.cs           → Aspire app host for samples

🏗️ Architecture Concepts

Widget/Node Pattern

Hex1b separates configuration (widgets) from rendering (nodes):

Important: Widgets are record types; Nodes are class types with mutable properties.

Reconciliation

The Hex1bApp.Reconcile() method diffs widgets against nodes:

• Same widget type → Update existing node's properties
• Different widget type → Create new node
• This preserves state (focus, cursor position) across re-renders

Layout System

Located in src/Hex1b/Layout/:

• Constraints - Min/max width/height bounds
• Size - Measured dimensions
• Rect - Position and size for arrangement
• SizeHint - Fill, Content, or Fixed sizing

Render Loop (in Hex1bApp.cs)

Build widgets → Reconcile → Measure → Arrange → Render → Wait for input → Repeat

📝 Code Conventions

Code Analysis Rules

This repo ships a Roslyn analyzer (src/Hex1b.Analyzers/) that runs against every project in the solution (lib, samples, tests, benchmarks) but is not packaged into the public Hex1b NuGet package. It enforces:

The API-design rules default to Warning severity and the lib builds under TreatWarningsAsErrors=true. HEX1B0011 is disabled by default and enabled via src/Hex1b/.editorconfig, so tests, samples, and other projects are unaffected. None of these analyzers are shipped to package consumers. Suppressions exist only where they encode a deliberate API decision (HEX1B0009 on Splitter's two-pane shape).

Tests for the analyzers live in tests/Hex1b.Analyzers.Tests/. New rules should follow the existing pattern: implement in src/Hex1b.Analyzers/, declare the ID in Hex1bDiagnosticIds.cs and AnalyzerReleases.Unshipped.md, and add positive + negative tests.

Naming

• Widgets: *Widget (e.g., TextBlockWidget, ButtonWidget) — enforced by HEX1B0002/HEX1B0004.
• Nodes: *Node (e.g., TextBlockNode, ButtonNode) — enforced by HEX1B0003/HEX1B0005.
• State objects: *State (e.g., TextBoxState) - for widgets requiring user-owned mutable state
• Widget configuration methods: never With* — that prefix is reserved for Hex1bTerminalBuilder. Use On* for event handlers and verb-noun for properties (e.g., Title, MaxFloating, Disabled). Enforced by HEX1B0001.
• Widget extension method parameters (Flutter-style):
  • WidgetContext<T> receiver → context (HEX1B0006)
  • Widget instance receiver (this XxxWidget … or where TWidget : Hex1bWidget) → widget (HEX1B0007)
  • A single widget-builder callback (Func<…, Hex1bWidget> etc.) → builder (HEX1B0008)
  • Avoid having two builder callbacks on one method; if genuinely required, suppress HEX1B0009 with a justification (HEX1B0009)

Widget Definition Pattern

// Widgets are records with fluent methods for event handlers
public record ButtonWidget(string Label) : Hex1bWidget
{
    internal Func<ButtonClickedEventArgs, Task>? ClickHandler { get; init; }
    
    public ButtonWidget OnClick(Action<ButtonClickedEventArgs> handler)
        => this with { ClickHandler = args => { handler(args); return Task.CompletedTask; } };
    
    public ButtonWidget OnClick(Func<ButtonClickedEventArgs, Task> handler)
        => this with { ClickHandler = handler };
}

Node Definition Pattern

public class ButtonNode : Hex1bNode
{
    // Properties reconciled from widget
    public string Label { get; set; } = "";
    public Func<InputBindingActionContext, Task>? ClickAction { get; set; }
    
    // Focus state (mutable, preserved across reconciliation)
    public bool IsFocused { get; set; }
    
    // Required overrides
    public override void Measure(Constraints constraints) { /* ... */ }
    public override void Arrange(Rect rect) { /* ... */ }
    public override void Render(Hex1bRenderContext context) { /* ... */ }
}

Keybinding Rebinding Pattern

When widgets define input bindings in ConfigureDefaultBindings, use Triggers(ActionId, handler, desc) instead of Action(handler, desc) to make bindings rebindable:

// In Widget record:
public static readonly ActionId MyAction = new($"{nameof(MyWidget)}.{nameof(MyAction)}");

// In Node's ConfigureDefaultBindings:
bindings.Key(Hex1bKey.Enter).Triggers(MyWidget.MyAction, handler, "Description");

Users can then remap/alias/disable actions via InputBindings:

widget.InputBindings(b =>
{
    b.Remove(MyWidget.MyAction);  // remove default key
    b.Key(Hex1bKey.X).Triggers(MyWidget.MyAction);  // rebind to X
});

Adding New Widgets

📘 Use the widget-creator skill for comprehensive step-by-step guidance including templates, theming, and test patterns.

Quick checklist:

1. Create XxxWidget record in src/Hex1b/Widgets/
2. Create XxxNode class in src/Hex1b/Nodes/
3. Add extension methods in src/Hex1b/XxxExtensions.cs
4. Add theme elements in src/Hex1b/Theming/XxxTheme.cs
5. Write tests in tests/Hex1b.Tests/XxxNodeTests.cs

Test Conventions

📘 Use the test-fixer skill when tests pass locally but fail in CI, or exhibit timing-sensitive behavior.

Follow the MethodName_Scenario_ExpectedBehavior naming pattern:

[TestMethod]
public void Measure_WithConstraints_ReturnsExpectedSize()
{
    // Arrange, Act, Assert
}

Test projects use MSTest.Sdk with OutputType=Exe and Microsoft.Testing.Platform (MTP). Use [TestMethod] for facts, [TestMethod] [DataRow(...)] for theories, [TestInitialize]/[TestCleanup] for setup/teardown, and [DoNotParallelize] on a class to opt out of parallel execution. For collection-equality, single-element, and type-cast assertions, prefer the TestSeq helpers in tests/Shared/TestSeq.cs (auto-imported via Hex1b.Testing):

TestSeq.AreEqual(expected, actual);   // deep collection equality
var item = TestSeq.Single(items);     // assert single + return element
var node = TestSeq.IsType<MyNode>(x); // assert type + return cast value

🔧 Common Tasks

Building

dotnet build

Running Tests

dotnet test

Running a Sample

dotnet run --project samples/Cancellation

🚀 .NET Aspire

📘 Use the aspire skill for detailed Aspire workflows, MCP tools, debugging, and integration guidance.

Aspire orchestrates sample applications. Resources are defined in apphost.cs.

Quick Commands

aspire run              # Run the app host
aspire run --detach     # Run in background (for agent environments)
aspire stop             # Stop running instances
aspire update           # Update Aspire packages

Key Points

• Changes to apphost.cs require restart
• Use Aspire MCP tools (list_resources, list_structured_logs, etc.) for debugging
• Avoid persistent containers early in development

⚠️ Important Constraints

Terminal Limitations

• No mouse support currently (keyboard-only navigation)
• Relies on ANSI escape sequences
• Alternate screen buffer used (\x1b[?1049h / \x1b[?1049l)

Focus System

• Focusable nodes: TextBoxNode, ButtonNode, ListNode
• Focus navigation: Tab (forward), Shift+Tab (backward), Escape (up to parent)
• Parent containers manage focus among children

Input Handling

• Input flows from IHex1bTerminal → Hex1bApp → InputRouter → focused Node
• InputBindings are checked before standard input handling
• Return InputResult.Handled from HandleInput if the input was consumed

🎯 When Making Changes

DO:

• ✅ Run tests after changes: dotnet test
• ✅ Follow existing patterns for new widgets/nodes
• ✅ Keep widgets immutable (use record)
• ✅ Preserve node state during reconciliation
• ✅ Use nullable reference types properly

DON'T:

• ❌ Add mutable state to widgets
• ❌ Forget to add reconciliation for new widget types
• ❌ Skip writing tests for new functionality
• ❌ Break the render loop sequence

📚 Key Files to Understand

🧪 Testing

Running Tests

dotnet test

Unit Testing Nodes

• Create node directly, set properties, verify behavior
• Use Hex1bKeyEvent to simulate input
• Check measured size after Measure()

Integration Testing

• Use Hex1bApp with Hex1bAppWorkloadAdapter
• Test full widget → node → render cycle
• See tests/Hex1b.Tests/ for examples

💬 Asking for Help

When asking questions about this codebase:

1. Reference specific file paths
2. Mention whether you're working with widgets or nodes
3. Include relevant test context if debugging
4. Note any Aspire-specific requirements

This file is intended for AI coding agents. Humans should refer to CONTRIBUTING.md for contribution guidelines.