Add formalized diagnostic tracing system

[Aaronontheweb]

Summary

Closes #72

Implements a lightweight, zero-cost-when-disabled tracing system for debugging Termina TUI applications.

Key Features

• Custom abstraction over M.E.Logging - No direct dependency required
• Deferred string formatting - TraceEvent struct captures template + args, formats only when needed
• Lock-free file output - Uses Channel with single reader pattern to avoid blocking UI thread
• Category-based filtering - Focus, Layout, Input, Page, Reactive, Render, Platform
• Level-based filtering - Trace, Debug, Info, Warning, Error
• MEL integration - Optional LoggerTraceListener adapter
• DI extension methods - AddTerminaFileTracing, AddTerminaLoggerTracing

Default Behavior

Tracing is completely disabled by default. When no listener is configured:

• All trace calls are no-ops (single inlined boolean check)
• No string formatting occurs
• No memory allocations occur
• No TraceEvent structs are created

Enabling Tracing

// 1. File tracing - lock-free channel design
services.AddTerminaFileTracing("termina-trace.log");

// 2. With category and level filtering
services.AddTerminaFileTracing(
    "termina-trace.log",
    TerminaTraceCategory.Focus | TerminaTraceCategory.Input,
    TerminaTraceLevel.Debug);

// 3. M.E.Logging integration
services.AddLogging(builder => builder.AddConsole())
        .AddTerminaLoggerTracing();

// 4. Stderr output (debugging without file I/O)
TerminaTrace.Configure(
    FileTraceListener.CreateStdErr(),
    TerminaTraceCategory.All,
    TerminaTraceLevel.Debug);

Output Format

2024-01-15 10:30:45.123 [DEBUG] [Focus] FocusManager#12345678 - PushFocus: TextInputNode, stack depth=1
2024-01-15 10:30:45.125 [TRACE] [Input] TextInputNode#87654321 - HandleInput: key=A, char='A'

Architecture Decisions (per user requirements)

• TraceEvent struct - Captures timestamp, level, category, source at creation; formats only when listener needs it
• Lock-free FileTraceListener - Unbounded channel with TryWrite (non-blocking), background task consumes
• Zero allocation when disabled - Template args stored in struct, string.Format only called when logging

Components with Tracing

• FocusManager - Focus push/pop/route operations
• TerminaApplication - Input processing, navigation, lifecycle
• TextInputNode - Focus events, key handling

Benchmark Results

Benchmarks confirm zero-cost-when-disabled design goal:

Disabled (No Listener) - Zero overhead

Method	Mean	Allocated
Disabled_NoArgs	~1 ns	0 B
Disabled_OneArg	~1 ns	0 B
Disabled_TwoArgs	~1 ns	0 B
Disabled_ThreeArgs	~1 ns	0 B

Enabled with Null Listener (TraceEvent creation only)

Method	Mean	Allocated
NullListener_NoArgs	~29 ns	0 B
NullListener_OneArg	~32 ns	24 B
NullListener_TwoArgs	~32 ns	24 B
NullListener_ThreeArgs	~37 ns	48 B

Enabled with Formatting (full cost)

Method	Mean	Allocated
Formatting_NoArgs	~64 ns	80 B
Formatting_OneArg	~78 ns	104 B
Formatting_TwoArgs	~87 ns	104 B
Formatting_ThreeArgs	~110 ns	128 B

Key takeaway: When disabled, tracing has <1ns overhead and zero allocations - the check is a single inlined boolean test.

Demo App Integration

The Termina.Demo app now includes file tracing:

• Logs go to %TEMP%/termina-logs/trace-{timestamp}.log
• Trace file path displayed in status bar
• README added with usage instructions for interactive and headless modes

# Interactive
dotnet run --project demos/Termina.Demo

# Headless/CI mode
dotnet run --project demos/Termina.Demo -- --test

Documentation

Added comprehensive documentation at docs/advanced/diagnostics.md covering:

• Default behavior and enabling tracing
• Category and level filtering
• Output format
• Adding traces to custom code
• Custom listener implementation
• Performance characteristics
• Best practices

Test plan

• Build passes
• All 635 tests pass
• Benchmark project builds
• Run benchmarks - verified zero allocations when disabled
• Test file tracing with demo app
• Documentation added
• Test MEL integration