first commit

2026-09-03 04:45:36 +03:00
commit d5f52cc3d3
1038 changed files with 169579 additions and 0 deletions
@@ -0,0 +1,661 @@
+# Cross-Platform UI Considerations
+
+<cite>
+**Referenced Files in This Document**
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
+- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
+- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+- [MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs)
+- [WPFDispatcher.cs](file://ClassicAssist/WPFDispatcher.cs)
+- [WPFUIInvoker.cs](file://ClassicAssist/WPFUIInvoker.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Platform-Specific Behaviors](#platform-specific-behaviors)
+7. [Dispatcher System and Thread Marshaling](#dispatcher-system-and-thread-marshaling)
+8. [Keyboard Handling Differences](#keyboard-handling-differences)
+9. [File System Access Patterns](#file-system-access-patterns)
+10. [Native Integration Points](#native-integration-points)
+11. [Testing Strategies](#testing-strategies)
+12. [Debugging Techniques](#debugging-techniques)
+13. [Best Practices for Platform-Agnostic Code](#best-practices-for-platform-agnostic-code)
+14. [Conclusion](#conclusion)
+
+## Introduction
+
+This document provides comprehensive guidance for developing cross-platform user interfaces in ClassicAssist.Avalonia, focusing on platform-specific behaviors, rendering differences, and compatibility considerations across Windows, macOS, and Linux platforms. It covers the dispatcher system for thread marshaling, UI invoker patterns, platform abstraction layers, keyboard handling differences, file system access patterns, and native integration points.
+
+The ClassicAssist.Avalonia project implements a sophisticated cross-platform architecture that abstracts platform-specific details while maintaining optimal performance and native feel across different operating systems. Understanding these patterns is crucial for developers working on UI components that need to function consistently across all supported platforms.
+
+## Project Structure
+
+The ClassicAssist.Avalonia project follows a modular architecture that separates platform-specific implementations from shared logic:
+
+```mermaid
+graph TB
+subgraph "Shared Layer"
+Shared["ClassicAssist.Shared"]
+IDispatcher["IDispatcher Interface"]
+IUIInvoker["IUIInvoker Interface"]
+PlatformDetector["PlatformDetector"]
+end
+subgraph "Avalonia Implementation"
+Avalonia["ClassicAssist.Avalonia"]
+AvaloniaDispatcher["AvaloniaDispatcher"]
+AvaloniaUIInvoker["AvaloniaUIInvoker"]
+App["App.axaml.cs"]
+Program["Program.cs"]
+end
+subgraph "WPF Legacy"
+WPF["ClassicAssist"]
+WPFDispatcher["WPFDispatcher"]
+WPFUIInvoker["WPFUIInvoker"]
+end
+Shared --> Avalonia
+Shared --> WPF
+IDispatcher --> AvaloniaDispatcher
+IUIInvoker --> AvaloniaUIInvoker
+PlatformDetector --> Avalonia
+App --> AvaloniaDispatcher
+Program --> App
+```
+
+**Diagram sources**
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
+- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
+- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+**Section sources**
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+
+## Core Components
+
+The cross-platform UI architecture is built around several core components that provide abstraction over platform-specific implementations:
+
+### Dispatcher Abstraction
+The `IDispatcher` interface defines a contract for thread marshaling operations, allowing UI updates to be safely executed on the appropriate thread regardless of the underlying platform.
+
+### UI Invoker Pattern
+The `IUIInvoker` interface provides a consistent API for invoking UI operations across different platforms, abstracting away the complexities of platform-specific threading models.
+
+### Platform Detection
+The `PlatformDetector` class provides utilities for detecting the current operating system and making platform-specific decisions at runtime.
+
+**Section sources**
+- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
+- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+## Architecture Overview
+
+The ClassicAssist.Avalonia architecture implements a layered approach to cross-platform UI development:
+
+```mermaid
+sequenceDiagram
+participant ViewModel as "ViewModel"
+participant Dispatcher as "IDispatcher"
+participant AvaloniaDisp as "AvaloniaDispatcher"
+participant UIThread as "UI Thread"
+ViewModel->>Dispatcher : InvokeOnUiThread(action)
+Dispatcher->>AvaloniaDisp : Dispatch action
+AvaloniaDisp->>UIThread : Marshal to UI thread
+UIThread-->>AvaloniaDisp : Execute action
+AvaloniaDisp-->>Dispatcher : Complete
+Dispatcher-->>ViewModel : Action completed
+```
+
+**Diagram sources**
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
+
+The architecture ensures that UI updates are always performed on the correct thread while providing a consistent API across different platforms. This design pattern prevents common threading issues and ensures smooth operation across Windows, macOS, and Linux environments.
+
+## Detailed Component Analysis
+
+### Dispatcher System Implementation
+
+The dispatcher system provides thread-safe UI updates through a well-defined abstraction layer:
+
+```mermaid
+classDiagram
+class IDispatcher {
+<<interface>>
+InvokeOnUiThread(action) void
+BeginInvokeOnUiThread(action) void
+IsOnUIThread() bool
+}
+class AvaloniaDispatcher {
+-_dispatcher Avalonia.Threading.Dispatcher
+InvokeOnUiThread(action) void
+BeginInvokeOnUiThread(action) void
+IsOnUIThread() bool
+-EnsureDispatcherInitialized() void
+}
+class WPFDispatcher {
+-_dispatcher System.Windows.Threading.Dispatcher
+InvokeOnUiThread(action) void
+BeginInvokeOnUiThread(action) void
+IsOnUIThread() bool
+}
+IDispatcher <|.. AvaloniaDispatcher
+IDispatcher <|.. WPFDispatcher
+AvaloniaDispatcher --> Avalonia.Threading.Dispatcher : "uses"
+WPFDispatcher --> System.Windows.Threading.Dispatcher : "uses"
+```
+
+**Diagram sources**
+- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+- [WPFDispatcher.cs](file://ClassicAssist/WPFDispatcher.cs)
+
+The dispatcher implementation handles platform-specific threading concerns while providing a unified interface for UI thread marshaling. This approach allows the same business logic to work seamlessly across different UI frameworks.
+
+### UI Invoker Pattern
+
+The UI invoker pattern provides a higher-level abstraction for common UI operations:
+
+```mermaid
+flowchart TD
+Start([UI Operation Request]) --> CheckThread{"On UI Thread?"}
+CheckThread --> |Yes| ExecuteDirect["Execute Directly"]
+CheckThread --> |No| UseDispatcher["Use Dispatcher"]
+UseDispatcher --> MarshalToUI["Marshal to UI Thread"]
+MarshalToUI --> ExecuteOnUI["Execute on UI Thread"]
+ExecuteDirect --> Complete([Operation Complete])
+ExecuteOnUI --> Complete
+```
+
+**Diagram sources**
+- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
+- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
+
+This pattern ensures that UI operations are always executed on the appropriate thread, preventing race conditions and ensuring thread safety across all platforms.
+
+**Section sources**
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
+- [WPFDispatcher.cs](file://ClassicAssist/WPFDispatcher.cs)
+- [WPFUIInvoker.cs](file://ClassicAssist/WPFUIInvoker.cs)
+
+## Platform-Specific Behaviors
+
+### Window Management Differences
+
+Each platform has distinct window management characteristics that affect how windows are created, displayed, and managed:
+
+#### Windows Platform
+- Uses Win32 API for advanced window features
+- Supports hardware acceleration by default
+- Handles DPI scaling automatically
+- Provides native context menus and tooltips
+
+#### macOS Platform
+- Integrates with Cocoa framework
+- Supports native menu bars and dock integration
+- Implements proper window lifecycle management
+- Handles Retina display scaling
+
+#### Linux Platform
+- Depends on X11 or Wayland backend
+- May require additional configuration for hardware acceleration
+- Varies significantly between distributions
+- Limited support for some advanced features
+
+### Rendering Differences
+
+Avalonia provides consistent rendering across platforms, but certain visual elements may render differently:
+
+```mermaid
+graph LR
+subgraph "Rendering Pipeline"
+XAML["XAML/UI Definition"]
+AvaloniaRenderer["Avalonia Renderer"]
+PlatformBackend["Platform Backend"]
+end
+subgraph "Windows"
+WinRT["WinRT/DirectX"]
+WGL["OpenGL"]
+end
+subgraph "macOS"
+Metal["Metal"]
+OpenGL["OpenGL"]
+end
+subgraph "Linux"
+X11["X11"]
+Wayland["Wayland"]
+Vulkan["Vulkan"]
+end
+AvaloniaRenderer --> PlatformBackend
+PlatformBackend --> WinRT
+PlatformBackend --> Metal
+PlatformBackend --> X11
+```
+
+**Diagram sources**
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+
+### Font and Text Rendering
+
+Font rendering varies across platforms due to different text measurement engines:
+
+- **Windows**: Uses ClearType for enhanced text clarity
+- **macOS**: Leverages Core Text for native font rendering
+- **Linux**: Depends on FreeType and system font configuration
+
+**Section sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+## Dispatcher System and Thread Marshaling
+
+### Thread Safety Considerations
+
+Cross-platform applications must handle threading carefully, as each platform has different threading models and constraints:
+
+```mermaid
+stateDiagram-v2
+[*] --> BackgroundThread
+BackgroundThread --> UIUpdateRequired : "Need to update UI"
+UIUpdateRequired --> DispatcherQueue : "Queue UI operation"
+DispatcherQueue --> UIThread : "Dispatch to UI thread"
+UIThread --> UIUpdate : "Execute UI update"
+UIUpdate --> [*]
+BackgroundThread --> ContinueProcessing : "Continue background work"
+ContinueProcessing --> [*]
+```
+
+**Diagram sources**
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+
+### Dispatcher Implementation Details
+
+The Avalonia dispatcher implementation leverages Avalonia's built-in threading infrastructure:
+
+- **Automatic Thread Detection**: Detects whether code is running on the UI thread
+- **Synchronous and Asynchronous Operations**: Supports both immediate and deferred UI updates
+- **Exception Handling**: Properly propagates exceptions from UI thread operations
+- **Performance Optimization**: Minimizes overhead for frequent UI updates
+
+### Best Practices for Thread Marshaling
+
+1. **Always use the dispatcher** for UI updates from background threads
+2. **Avoid blocking the UI thread** with long-running operations
+3. **Handle exceptions** properly in dispatched operations
+4. **Consider performance implications** of frequent UI updates
+5. **Test thoroughly** on all target platforms
+
+**Section sources**
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
+
+## Keyboard Handling Differences
+
+### Key Event Processing
+
+Keyboard input handling varies significantly across platforms:
+
+#### Windows Platform
+- Uses Win32 key codes and virtual key codes
+- Supports advanced input features like raw input
+- Handles modifier keys consistently
+- Provides detailed key state information
+
+#### macOS Platform
+- Uses Carbon/Cocoa key event system
+- Different modifier key behavior (Command vs Control)
+- International keyboard layout support
+- Special handling for function keys
+
+#### Linux Platform
+- Depends on X11 or Wayland input system
+- Variable support for special keys
+- Distribution-dependent behavior
+- May require additional configuration for full functionality
+
+### Platform-Specific Key Mappings
+
+```mermaid
+flowchart TD
+KeyPress["Key Press Event"] --> PlatformCheck{"Platform Detection"}
+PlatformCheck --> |Windows| WinKeys["Windows Key Codes"]
+PlatformCheck --> |macOS| MacKeys["macOS Key Codes"]
+PlatformCheck --> |Linux| LinKeys["Linux Key Codes"]
+WinKeys --> Normalize["Normalize to Common Format"]
+MacKeys --> Normalize
+LinKeys --> Normalize
+Normalize --> ApplicationLogic["Application Logic"]
+ApplicationLogic --> Response["UI Response"]
+```
+
+**Diagram sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+### Best Practices for Keyboard Input
+
+1. **Abstract key handling** behind platform-independent interfaces
+2. **Test keyboard shortcuts** on all target platforms
+3. **Handle international keyboards** appropriately
+4. **Provide fallback mechanisms** for unsupported keys
+5. **Document platform-specific behaviors** clearly
+
+## File System Access Patterns
+
+### Cross-Platform File Operations
+
+File system access requires careful consideration of platform differences:
+
+```mermaid
+graph TB
+subgraph "Application Layer"
+FileSystemAPI["FileSystem API"]
+PathUtilities["Path Utilities"]
+end
+subgraph "Platform Abstraction"
+PathSeparator["Path Separator Handler"]
+PermissionHandler["Permission Handler"]
+EncodingHandler["Encoding Handler"]
+end
+subgraph "Platform Implementations"
+WinFS["Windows File System"]
+MacFS["macOS File System"]
+LinuxFS["Linux File System"]
+end
+FileSystemAPI --> PathUtilities
+PathUtilities --> PathSeparator
+PathUtilities --> PermissionHandler
+PathUtilities --> EncodingHandler
+PathSeparator --> WinFS
+PathSeparator --> MacFS
+PathSeparator --> LinuxFS
+PermissionHandler --> WinFS
+PermissionHandler --> MacFS
+PermissionHandler --> LinuxFS
+EncodingHandler --> WinFS
+EncodingHandler --> MacFS
+EncodingHandler --> LinuxFS
+```
+
+**Diagram sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+### Path Handling Differences
+
+- **Windows**: Uses backslashes (`\`) as path separators
+- **macOS/Linux**: Uses forward slashes (`/`) as path separators
+- **Case Sensitivity**: Linux/macOS are case-sensitive; Windows is not
+- **Drive Letters**: Only Windows uses drive letters (C:, D:)
+
+### File Permissions and Security
+
+Each platform has different permission models:
+
+- **Windows**: ACL-based permissions with user/group model
+- **macOS**: Unix-style permissions with extended attributes
+- **Linux**: Traditional Unix permissions with SELinux/AppArmor support
+
+**Section sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+## Native Integration Points
+
+### Platform-Specific APIs
+
+The application integrates with platform-specific APIs for enhanced functionality:
+
+#### Windows Integration
+- Registry access for settings storage
+- Windows Forms interop for legacy components
+- DirectX integration for graphics acceleration
+- Windows notification system integration
+
+#### macOS Integration
+- Cocoa framework integration
+- NSUserDefaults for preferences
+- Spotlight indexing support
+- Notification center integration
+
+#### Linux Integration
+- Desktop environment integration (GNOME, KDE)
+- System tray integration
+- MIME type handling
+- File association management
+
+### Native Method Calls
+
+```mermaid
+sequenceDiagram
+participant App as "Application"
+participant NativeBridge as "Native Bridge"
+participant OS as "Operating System"
+App->>NativeBridge : Call Native Function
+NativeBridge->>OS : Platform-Specific API Call
+OS-->>NativeBridge : Result Data
+NativeBridge-->>App : Processed Result
+Note over App,OS : Platform abstraction layer handles<br/>different calling conventions and data types
+```
+
+**Diagram sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+### Memory Management Considerations
+
+Different platforms have varying memory management requirements:
+
+- **Windows**: COM objects require proper cleanup
+- **macOS**: ARC-managed objects with manual bridging
+- **Linux**: Manual memory management for native libraries
+
+**Section sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+## Testing Strategies
+
+### Cross-Platform Testing Approach
+
+Testing cross-platform UI components requires a multi-faceted approach:
+
+```mermaid
+flowchart TD
+UnitTests["Unit Tests"] --> MockPlatform["Mock Platform Services"]
+UnitTests --> BusinessLogic["Business Logic Validation"]
+IntegrationTests["Integration Tests"] --> TestEnvironment["Test Environment Setup"]
+IntegrationTests --> PlatformAbstractions["Platform Abstractions"]
+UIAutomation["UI Automation"] --> HeadlessBrowser["Headless Browser Testing"]
+UIAutomation --> ScreenCapture["Screen Capture Analysis"]
+ManualTesting["Manual Testing"] --> AllPlatforms["All Target Platforms"]
+ManualTesting --> UserScenarios["Real User Scenarios"]
+AllPlatforms --> Windows["Windows Testing"]
+AllPlatforms --> macOS["macOS Testing"]
+AllPlatforms --> Linux["Linux Testing"]
+```
+
+**Diagram sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+### Platform-Specific Test Cases
+
+#### Windows-Specific Tests
+- Registry access and modification
+- Windows Forms interoperability
+- Hardware acceleration verification
+- DPI scaling validation
+
+#### macOS-Specific Tests
+- Cocoa framework integration
+- Menu bar functionality
+- Dock integration
+- Retina display rendering
+
+#### Linux-Specific Tests
+- Desktop environment compatibility
+- File manager integration
+- System theme adherence
+- Package manager integration
+
+### Continuous Integration Setup
+
+```mermaid
+graph LR
+subgraph "CI Pipeline"
+Build["Build Stage"]
+UnitTest["Unit Tests"]
+IntegrationTest["Integration Tests"]
+PlatformTest["Platform-Specific Tests"]
+Deployment["Deployment"]
+end
+subgraph "Platforms"
+Win["Windows VM"]
+Mac["macOS VM"]
+Lin["Linux VM"]
+end
+Build --> UnitTest
+UnitTest --> IntegrationTest
+IntegrationTest --> PlatformTest
+PlatformTest --> Win
+PlatformTest --> Mac
+PlatformTest --> Lin
+Win --> Deployment
+Mac --> Deployment
+Lin --> Deployment
+```
+
+**Diagram sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+## Debugging Techniques
+
+### Platform-Specific Debugging Tools
+
+#### Windows Debugging
+- Visual Studio debugger with .NET debugging
+- WinDbg for low-level analysis
+- Performance Profiler for resource usage
+- Network traffic monitoring
+
+#### macOS Debugging
+- Xcode debugger with LLDB
+- Instruments for performance analysis
+- Console.app for system logs
+- Activity Monitor for resource usage
+
+#### Linux Debugging
+- GDB for source-level debugging
+- Valgrind for memory leak detection
+- strace for system call tracing
+- dmesg for kernel messages
+
+### Common Cross-Platform Issues
+
+```mermaid
+flowchart TD
+IssueDetected["Issue Detected"] --> PlatformIdentify{"Identify Platform"}
+PlatformIdentify --> WinIssues["Windows-Specific Issues"]
+PlatformIdentify --> MacIssues["macOS-Specific Issues"]
+PlatformIdentify --> LinIssues["Linux-Specific Issues"]
+WinIssues --> WinTools["Windows Debug Tools"]
+MacIssues --> MacTools["macOS Debug Tools"]
+LinIssues --> LinTools["Linux Debug Tools"]
+WinTools --> Resolution["Resolution Strategy"]
+MacTools --> Resolution
+LinTools --> Resolution
+Resolution --> VerifyFix["Verify Fix on All Platforms"]
+VerifyFix --> DeployFix["Deploy Fix"]
+```
+
+**Diagram sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+### Logging and Diagnostics
+
+Implement comprehensive logging that works across all platforms:
+
+- **Structured Logging**: Use JSON-formatted logs for easy parsing
+- **Platform Context**: Include platform information in log entries
+- **Performance Metrics**: Track performance indicators per platform
+- **Error Aggregation**: Centralize error reporting across platforms
+
+**Section sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+## Best Practices for Platform-Agnostic Code
+
+### Design Principles
+
+1. **Interface-Based Design**: Define clear interfaces for platform-specific functionality
+2. **Dependency Injection**: Use DI containers to inject platform-specific implementations
+3. **Configuration-Driven Behavior**: Make platform-specific behavior configurable
+4. **Graceful Degradation**: Provide fallbacks when platform features are unavailable
+
+### Code Organization
+
+```mermaid
+graph TB
+subgraph "Shared Code"
+Interfaces["Interfaces & Contracts"]
+Models["Data Models"]
+Algorithms["Platform-Independent Algorithms"]
+end
+subgraph "Platform Implementations"
+WinImpl["Windows Implementation"]
+MacImpl["macOS Implementation"]
+LinImpl["Linux Implementation"]
+end
+subgraph "UI Layer"
+Views["Platform-Agnostic Views"]
+ViewModels["Shared ViewModels"]
+end
+Interfaces --> WinImpl
+Interfaces --> MacImpl
+Interfaces --> LinImpl
+Models --> Views
+Models --> ViewModels
+Algorithms --> ViewModels
+Algorithms --> Views
+```
+
+**Diagram sources**
+- [PlatformDetector.cs](file://ClassicAssist.Shared/Engine/PlatformDetector.cs)
+
+### Conditional Compilation vs Runtime Detection
+
+Choose the appropriate approach based on complexity:
+
+- **Conditional Compilation**: For significant architectural differences
+- **Runtime Detection**: For minor behavioral variations
+- **Feature Flags**: For optional platform-specific features
+
+### Error Handling Strategies
+
+Implement robust error handling that accounts for platform differences:
+
+- **Platform-Specific Error Messages**: Provide meaningful error messages for each platform
+- **Fallback Mechanisms**: Gracefully handle missing platform features
+- **Diagnostic Information**: Collect platform-specific diagnostic data
+- **User-Friendly Recovery**: Guide users through platform-specific recovery steps
+
+## Conclusion
+
+Developing cross-platform UI applications with ClassicAssist.Avalonia requires careful consideration of platform-specific behaviors, threading models, and system integrations. The architecture presented in this document provides a solid foundation for building maintainable and performant cross-platform applications.
+
+Key takeaways include:
+
+1. **Abstraction Layers**: Use well-defined interfaces to abstract platform-specific details
+2. **Thread Safety**: Always use the dispatcher system for UI updates from background threads
+3. **Platform Detection**: Implement robust platform detection for conditional behavior
+4. **Comprehensive Testing**: Test thoroughly on all target platforms
+5. **Graceful Degradation**: Handle missing platform features gracefully
+6. **Consistent User Experience**: Maintain consistent behavior across platforms while respecting platform conventions
+
+By following these guidelines and leveraging the provided abstractions, developers can create high-quality cross-platform applications that provide excellent user experiences on Windows, macOS, and Linux platforms.
@@ -0,0 +1,413 @@
+# Custom Controls Library
+
+<cite>
+**Referenced Files in This Document**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendices](#appendices)
+
+## Introduction
+This document provides comprehensive documentation for the custom control library in ClassicAssist.Avalonia, focusing on four key controls: HexDumpControl (binary data visualization), EditTextBlock (editable text display), TextBoxKey (key binding input), and HueEntryControl (color selection). It explains their properties, events, styling options, integration patterns, inheritance hierarchy, extension points, performance considerations, memory management, and best practices within the Avalonia framework.
+
+## Project Structure
+The custom controls are implemented under ClassicAssist.Avalonia/Controls with associated XAML markup (.axaml) and code-behind (.axaml.cs). Supporting converters and theme resources reside under ClassicAssist.Avalonia/Misc and ClassicAssist.Avalonia/Controls respectively.
+
+```mermaid
+graph TB
+subgraph "Controls"
+HDC["HexDumpControl.axaml<br/>HexDumpControl.axaml.cs"]
+EBT["EditTextBlock.axaml<br/>EditTextBlock.axaml.cs"]
+TBK["TextBoxKey.axaml<br/>TextBoxKey.axaml.cs"]
+HEC["HueEntryControl.axaml<br/>HueEntryControl.axaml.cs"]
+GBX["GroupBox.cs<br/>GroupBox.Theme.xaml"]
+end
+subgraph "Misc"
+CONV["HueEntryToRectanglesValueConverter.cs"]
+end
+HDC --> |uses| CONV
+HEC --> |uses| CONV
+EBT --> |styling| GBX
+TBK --> |styling| GBX
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+**Section sources**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+## Core Components
+- HexDumpControl: Renders a scrollable hex dump view for binary data. Typically binds to a byte array or stream and exposes properties for offset, length, and formatting options. Supports virtualization-friendly rendering and keyboard navigation.
+- EditTextBlock: Provides an inline editable text block that can switch between display and edit modes. Exposes Text, IsReadOnly, and editing-related commands/events. Integrates with Avalonia’s focus and clipboard behaviors.
+- TextBoxKey: Specialized input control for capturing key bindings. Handles KeyDown/KeyUp events, supports modifiers, and exposes a bound KeyCombination property. Useful for hotkey configuration UIs.
+- HueEntryControl: Color picker entry control for selecting hues. Uses a converter to render hue rectangles and exposes SelectedHue and related properties. Integrates with color pickers and themes.
+
+Integration patterns:
+- Bind properties using Avalonia’s two-way binding in XAML.
+- Subscribe to events in code-behind or via command bindings in ViewModels.
+- Style controls using ResourceDictionaries and ControlTemplates.
+
+**Section sources**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+
+## Architecture Overview
+The controls follow standard Avalonia patterns:
+- Each control has an .axaml file defining its visual tree and an .axaml.cs file implementing behavior.
+- Converters transform model values into presentation-ready structures (e.g., hue rectangles).
+- Theme resources define default styles and templates.
+
+```mermaid
+classDiagram
+class HexDumpControl {
+Properties
+Events
+RenderingLogic()
+}
+class EditTextBlock {
+Text
+IsReadOnly
+EditMode(bool)
+TextChangedEvent
+}
+class TextBoxKey {
+KeyCombination
+KeyDownHandler()
+KeyUpHandler()
+}
+class HueEntryControl {
+SelectedHue
+RenderHueRectangles()
+}
+class HueEntryToRectanglesValueConverter {
+Convert(value)
+}
+class GroupBox {
+Header
+Content
+}
+HueEntryControl --> HueEntryToRectanglesValueConverter : "uses"
+EditTextBlock --> GroupBox : "styled by"
+TextBoxKey --> GroupBox : "styled by"
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+
+## Detailed Component Analysis
+
+### HexDumpControl
+Purpose:
+- Visualize binary data as a hex dump with row/column layout, optional ASCII column, and selectable ranges.
+
+Key responsibilities:
+- Data binding to byte sequences.
+- Rendering rows and columns efficiently.
+- Handling scrolling and selection.
+- Keyboard navigation and copy operations.
+
+Typical properties and events:
+- Properties: Data source (byte array/stream), Offset, Length, BytesPerRow, ShowAscii, SelectionStart, SelectionLength.
+- Events: SelectionChanged, DataUpdated, CopyRequested.
+
+Styling options:
+- Background/foreground colors for selected bytes.
+- Font family and size for monospaced rendering.
+- Row header visibility and width.
+
+Integration examples:
+- XAML binding to a ViewModel property exposing a byte array.
+- Code-behind subscription to SelectionChanged to update status bar.
+
+```mermaid
+sequenceDiagram
+participant VM as "ViewModel"
+participant HDC as "HexDumpControl"
+participant Render as "Renderer"
+VM->>HDC : Set Data Source
+HDC->>Render : Build Rows/Cols
+Render-->>HDC : Visual Tree Updated
+HDC-->>VM : SelectionChanged Event
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+
+**Section sources**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+
+### EditTextBlock
+Purpose:
+- Provide an inline text block that can be toggled into edit mode, supporting clipboard operations and validation.
+
+Key responsibilities:
+- Switching between display and edit modes.
+- Managing focus and caret position.
+- Validating and committing changes.
+
+Typical properties and events:
+- Properties: Text, IsReadOnly, MaxLength, ValidationMessage.
+- Events: TextChanged, EditModeChanged, CommitRequested.
+
+Styling options:
+- Default text style vs. editor style.
+- Border and background when in edit mode.
+- Error highlighting.
+
+Integration examples:
+- Two-way binding to a string property in ViewModel.
+- Command binding to commit edits on Enter or focus loss.
+
+```mermaid
+flowchart TD
+Start(["User Interaction"]) --> ModeCheck{"Is ReadOnly?"}
+ModeCheck --> |Yes| Display["Display Mode"]
+ModeCheck --> |No| ToggleEdit["Toggle Edit Mode"]
+ToggleEdit --> FocusEditor["Focus Editor"]
+FocusEditor --> Validate["Validate Input"]
+Validate --> Valid{"Valid?"}
+Valid --> |Yes| Commit["Commit Changes"]
+Valid --> |No| ShowError["Show Validation Message"]
+Commit --> End(["Exit Edit Mode"])
+ShowError --> End
+Display --> End
+```
+
+**Diagram sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+**Section sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+### TextBoxKey
+Purpose:
+- Capture user key combinations for hotkey configuration.
+
+Key responsibilities:
+- Listening to KeyDown/KeyUp events.
+- Building a KeyCombination from pressed keys and modifiers.
+- Preventing default actions for captured keys.
+
+Typical properties and events:
+- Properties: KeyCombination, PlaceholderText, AllowModifiers.
+- Events: KeyCombinationChanged, ClearRequested.
+
+Styling options:
+- Visual feedback for active modifier keys.
+- Placeholder text styling.
+- Error state for invalid combinations.
+
+Integration examples:
+- Binding KeyCombination to a ViewModel property.
+- Using a command to clear the current combination.
+
+```mermaid
+sequenceDiagram
+participant User as "User"
+participant TBK as "TextBoxKey"
+participant VM as "ViewModel"
+User->>TBK : Press Keys
+TBK->>TBK : Update KeyCombination
+TBK-->>VM : KeyCombinationChanged Event
+VM-->>TBK : Optional Clear Command
+```
+
+**Diagram sources**
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+
+**Section sources**
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+
+### HueEntryControl
+Purpose:
+- Provide a compact color selection entry for choosing hues.
+
+Key responsibilities:
+- Rendering hue rectangles based on a palette.
+- Handling click/drag interactions to select hue.
+- Updating SelectedHue and notifying bindings.
+
+Typical properties and events:
+- Properties: SelectedHue, PaletteSource, ShowSwatches.
+- Events: HueSelected, PaletteChanged.
+
+Styling options:
+- Swatch size and spacing.
+- Highlight color for selected hue.
+- Tooltip content for hue value.
+
+Integration examples:
+- Binding SelectedHue to a color property in ViewModel.
+- Using a converter to map hue to visual rectangles.
+
+```mermaid
+classDiagram
+class HueEntryControl {
+SelectedHue
+PaletteSource
+OnHueSelected(hue)
+}
+class HueEntryToRectanglesValueConverter {
+Convert(palette) Rectangles[]
+}
+HueEntryControl --> HueEntryToRectanglesValueConverter : "converts palette"
+```
+
+**Diagram sources**
+- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+
+**Section sources**
+- [HueEntryControl.axaml](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+
+### Conceptual Overview
+These controls adhere to Avalonia’s composition model:
+- Declarative UI in .axaml files.
+- Behavior in .axaml.cs code-behind.
+- Styling via ResourceDictionaries and ControlTemplates.
+- Data binding through Avalonia’s binding engine.
+
+```mermaid
+graph TB
+AXAML[".axaml (UI)"]
+CODEBEHIND[".axaml.cs (Behavior)"]
+THEME["ResourceDictionary (Styles/Templates)"]
+BINDING["Avalonia Binding Engine"]
+AXAML --> CODEBEHIND
+AXAML --> THEME
+CODEBEHIND --> BINDING
+THEME --> BINDING
+```
+
+[No sources needed since this diagram shows conceptual workflow, not actual code structure]
+
+## Dependency Analysis
+- HueEntryControl depends on HueEntryToRectanglesValueConverter for rendering.
+- EditTextBlock and TextBoxKey rely on theme resources defined in GroupBox.Theme.xaml for consistent styling.
+- All controls integrate with Avalonia’s binding system and event infrastructure.
+
+```mermaid
+graph LR
+HEX["HexDumpControl"]
+EDIT["EditTextBlock"]
+KEY["TextBoxKey"]
+HUE["HueEntryControl"]
+CONV["HueEntryToRectanglesValueConverter"]
+THEME["GroupBox.Theme.xaml"]
+HUE --> CONV
+EDIT --> THEME
+KEY --> THEME
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+**Section sources**
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+## Performance Considerations
+- Virtualization: For large datasets (e.g., HexDumpControl), ensure only visible rows are rendered; consider virtualizing panels and lazy loading chunks.
+- Memory Management: Avoid retaining references to large buffers; use streams or segmented arrays where possible. Clear selections and caches on disposal.
+- Event Throttling: Debounce frequent updates (e.g., typing in EditTextBlock) to reduce binding churn.
+- Converter Efficiency: Keep converters lightweight; precompute immutable structures (e.g., hue rectangles) and cache results.
+- Styling Overhead: Minimize complex templates; prefer simple brushes and transforms.
+
+[No sources needed since this section provides general guidance]
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- Binding failures: Verify property names and DataContext; check Avalonia diagnostics output.
+- Focus problems in EditTextBlock: Ensure focus scope is correct and prevent focus loss during validation.
+- Key capture conflicts in TextBoxKey: Mark handled events appropriately to avoid propagation.
+- Hue rendering glitches: Confirm palette source is non-null and converter returns valid geometry.
+
+Best practices:
+- Use async operations for heavy work outside the UI thread.
+- Dispose unmanaged resources and detach event handlers in OnUnloaded.
+- Test with different themes and DPI settings.
+
+**Section sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [HueEntryControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HueEntryControl.axaml.cs)
+
+## Conclusion
+The custom controls in ClassicAssist.Avalonia provide robust, extensible building blocks for binary visualization, inline editing, key binding input, and color selection. By leveraging Avalonia’s declarative UI, binding engine, and theming system, these controls deliver high usability and performance. Follow the integration patterns and best practices outlined here to extend and customize controls effectively.
+
+[No sources needed since this section summarizes without analyzing specific files]
+
+## Appendices
+
+### Inheritance and Extension Patterns
+- Extend existing controls by deriving from base classes and overriding template parts.
+- Add new properties using Avalonia’s property system for binding support.
+- Implement custom templates in ResourceDictionaries to restyle controls without changing behavior.
+
+[No sources needed since this section doesn't analyze specific source files]
@@ -0,0 +1,227 @@
+# EditTextBlock
+
+<cite>
+**Referenced Files in This Document**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+
+## Introduction
+This document provides comprehensive documentation for the EditTextBlock control, which combines the visual appearance of a TextBlock with editable text functionality. It explains how to use and customize the control, including properties such as Text, IsReadOnly, MaxLength, and validation rules. It also covers the editing lifecycle, focus management, keyboard navigation behavior, two-way data binding, custom formatting, integration with validation frameworks, styling and template customization, accessibility features, and guidance on when to choose EditTextBlock versus TextBox.
+
+## Project Structure
+The EditTextBlock control is implemented in the Avalonia UI project under Controls. The control consists of an Axaml markup file that defines its visual structure and an associated code-behind file that implements its behavior and properties.
+
+```mermaid
+graph TB
+subgraph "Avalonia Project"
+A["Controls/EditTextBlock.axaml"]
+B["Controls/EditTextBlock.axaml.cs"]
+end
+A --> B
+```
+
+**Diagram sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+**Section sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+## Core Components
+- Visual layer: The Axaml markup defines the control’s visual tree, typically hosting a TextBlock for display and an internal TextBox for editing.
+- Behavior layer: The code-behind exposes dependency properties (e.g., Text, IsReadOnly, MaxLength), manages focus transitions between display and edit modes, and handles input events and validation.
+
+Key responsibilities:
+- Display mode: Render text using a TextBlock-like appearance.
+- Edit mode: Switch to an internal TextBox to allow user input.
+- Focus management: Capture and release focus appropriately during edit sessions.
+- Validation: Enforce constraints like MaxLength and integrate with validation logic.
+- Binding: Support two-way binding to Text and related properties.
+
+**Section sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+## Architecture Overview
+At runtime, EditTextBlock toggles between a read-only presentation and an inline editing experience. When the user initiates editing, the control focuses an internal TextBox; when editing completes or is canceled, it returns to the TextBlock-like presentation.
+
+```mermaid
+sequenceDiagram
+participant User as "User"
+participant Control as "EditTextBlock"
+participant Display as "TextBlock"
+participant Editor as "TextBox"
+User->>Control : Click to edit
+Control->>Editor : Show editor and set focus
+Editor-->>Control : Text changes (two-way binding)
+User->>Editor : Finish editing (Enter/blur)
+Control->>Display : Update display value
+Control->>Editor : Hide editor and clear focus
+```
+
+**Diagram sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+## Detailed Component Analysis
+
+### Properties and Data Binding
+- Text: Two-way bindable string property representing the current content. Updates propagate both from view model to control and from control to view model.
+- IsReadOnly: Boolean flag controlling whether the control allows editing. When true, the control remains in display mode.
+- MaxLength: Numeric constraint limiting the number of characters allowed in edit mode.
+
+Binding patterns:
+- Use two-way binding to keep the view model synchronized with user edits.
+- For read-only scenarios, bind IsReadOnly to a view model state.
+
+Validation integration:
+- Apply validation rules by handling change notifications or by wrapping the bound property with validation logic in the view model.
+- Enforce MaxLength at the control level to prevent invalid input early.
+
+**Section sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+### Editing Lifecycle
+The control follows a predictable lifecycle:
+- Entry into edit mode: On user action (e.g., click), the control switches to edit mode, focuses the internal TextBox, and selects existing text if appropriate.
+- During editing: The control listens to text changes and updates the backing property via two-way binding.
+- Exit from edit mode: On completion (e.g., Enter key or losing focus), the control validates input, applies constraints (like MaxLength), commits changes, and returns to display mode.
+
+```mermaid
+flowchart TD
+Start(["Edit initiated"]) --> FocusEditor["Focus internal TextBox"]
+FocusEditor --> InputLoop["User inputs text"]
+InputLoop --> ValidateInput{"Valid?"}
+ValidateInput --> |No| Reject["Reject input / show error"]
+ValidateInput --> |Yes| Commit["Commit changes"]
+Commit --> ExitMode["Exit edit mode"]
+ExitMode --> End(["Display updated"])
+Reject --> InputLoop
+```
+
+**Diagram sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+### Focus Management and Keyboard Navigation
+- Focus capture: The control programmatically focuses the internal TextBox when entering edit mode.
+- Focus release: The control clears focus when exiting edit mode, returning focus to the logical parent element if needed.
+- Keyboard behavior:
+  - Enter: Commits changes and exits edit mode.
+  - Escape: Cancels changes and reverts to previous value.
+  - Tab: Moves focus out of the control, triggering commit or cancel depending on implementation.
+  - Arrow keys and selection: Standard text editing behaviors are supported within the internal TextBox.
+
+Accessibility considerations:
+- Ensure proper AutomationPeer support so screen readers announce the control’s role and state.
+- Provide meaningful names and descriptions via accessible properties.
+
+**Section sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+### Styling and Template Customization
+- Style targets: You can style the control to match application themes, including fonts, colors, borders, and padding.
+- Template customization: Override the control template to replace the default visual tree while preserving behavior. Common customizations include:
+  - Adding icons or buttons adjacent to the text area.
+  - Changing layout orientation or alignment.
+  - Applying different visual states for hover, focus, and disabled.
+
+Best practices:
+- Keep the internal TextBox and TextBlock roles intact to preserve editing semantics.
+- Avoid removing focus-related elements required for accessibility.
+
+**Section sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+### Integration Examples
+
+#### Two-Way Data Binding
+Bind the Text property to a view model property with two-way mode. Changes made in the control update the view model automatically, and updates from the view model reflect in the control.
+
+#### Custom Formatting
+Use converters or formatters in bindings to format values for display while preserving raw values for editing. Alternatively, handle formatting in the control’s code-behind around edit entry and exit.
+
+#### Validation Frameworks
+Integrate with validation frameworks by:
+- Raising validation errors when MaxLength is exceeded.
+- Exposing a validation state property that can be bound to error indicators.
+- Using INotifyDataErrorInfo or similar patterns in the view model to report validation results.
+
+**Section sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+### When to Use EditTextBlock vs TextBox
+- Use EditTextBlock when:
+  - You want a compact, TextBlock-like appearance most of the time.
+  - Inline editing is preferred without introducing a full-width TextBox.
+  - Read-only and editable states need to switch seamlessly.
+- Use TextBox when:
+  - Users frequently enter large amounts of text.
+  - Complex editing features (multiline, rich editing) are required.
+  - The UI already emphasizes input fields and does not need a hybrid control.
+
+## Dependency Analysis
+EditTextBlock depends on Avalonia’s core controls and binding infrastructure. Its behavior relies on focus events, input handling, and dependency properties.
+
+```mermaid
+graph TB
+ETB["EditTextBlock.axaml.cs"]
+AXAML["EditTextBlock.axaml"]
+AV["Avalonia Core"]
+BIND["Avalonia Binding"]
+FOCUS["Focus System"]
+INPUT["Input Handling"]
+ETB --> AXAML
+ETB --> AV
+ETB --> BIND
+ETB --> FOCUS
+ETB --> INPUT
+```
+
+**Diagram sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+
+**Section sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+
+## Performance Considerations
+- Minimize unnecessary rebinds by avoiding excessive updates to the Text property.
+- Debounce heavy validation logic to avoid blocking the UI thread during typing.
+- Prefer lightweight templates and styles to reduce layout overhead.
+- Reuse resources (brushes, fonts) across instances where possible.
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- Binding not updating:
+  - Ensure two-way binding is configured correctly.
+  - Verify that the view model raises property change notifications.
+- Validation not triggering:
+  - Confirm that validation logic runs on relevant events (text changed, commit).
+  - Check that error states are exposed and bound to UI indicators.
+- Focus problems:
+  - Ensure the control captures focus on edit entry and releases it on exit.
+  - Test keyboard navigation across host containers.
+- Accessibility concerns:
+  - Verify that accessible names and roles are set.
+  - Test with a screen reader to confirm announcements.
+
+**Section sources**
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+
+## Conclusion
+EditTextBlock offers a streamlined way to present and edit text inline, combining the look of a TextBlock with the functionality of a TextBox. By leveraging its properties, lifecycle, and customization options, you can create intuitive interfaces that balance readability and editability. Choose EditTextBlock for compact inline editing scenarios and TextBox for more intensive input tasks.
@@ -0,0 +1,500 @@
+# HexDumpControl
+
+<cite>
+**Referenced Files in This Document**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
+- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendices](#appendices)
+
+## Introduction
+
+The HexDumpControl is a specialized binary data visualization control designed for displaying hexadecimal dumps with ASCII representation. This component serves as a critical debugging and analysis tool within the ClassicAssist application suite, providing developers and users with an intuitive interface for examining raw binary data packets, memory dumps, and other byte-oriented content.
+
+The control implements a dual-column layout showing both hexadecimal values and their corresponding ASCII representations, making it ideal for network packet inspection, file format analysis, and low-level debugging scenarios. It supports various display configurations, styling options, and interactive features to enhance the user experience when working with large datasets.
+
+## Project Structure
+
+The HexDumpControl is implemented as part of the ClassicAssist.Avalonia project, following Avalonia UI framework conventions. The component consists of two primary files:
+
+```mermaid
+graph TB
+subgraph "ClassicAssist.Avalonia/Controls"
+HXAML[HexDumpControl.axaml]
+HCS[HexDumpControl.axaml.cs]
+end
+subgraph "ClassicAssist.Avalonia/Misc"
+BIN_CONV[PacketEntryBinaryValueConverter.cs]
+TXT_CONV[PacketEntryTextValueConverter.cs]
+end
+HXAML --> HCS
+HCS --> BIN_CONV
+HCS --> TXT_CONV
+subgraph "Dependencies"
+AVA[Avalonia Framework]
+BIND[Data Binding Engine]
+STY[Styling System]
+end
+HCS --> AVA
+HCS --> BIND
+HCS --> STY
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml:1-50](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L50)
+- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
+- [PacketEntryBinaryValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L50)
+- [PacketEntryTextValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L50)
+
+**Section sources**
+- [HexDumpControl.axaml:1-200](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L200)
+- [HexDumpControl.axaml.cs:1-300](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L300)
+
+## Core Components
+
+The HexDumpControl exposes several key public properties that define its behavior and appearance:
+
+### Data Property
+The primary data source property that accepts byte arrays or collections of bytes for display. This property supports both static data binding and dynamic updates through observable collections.
+
+### ShowAddress Property
+A boolean flag that controls the visibility of address columns in the hex dump display. When enabled, each row displays the starting memory offset for that line of data.
+
+### ShowAscii Property
+A boolean flag that toggles the visibility of the ASCII representation column alongside the hexadecimal values.
+
+### AddressFormat Property
+An enumeration or string format specifier that determines how memory addresses are displayed (e.g., hexadecimal, decimal, or custom formats).
+
+### Styling Options
+The control provides extensive styling capabilities including:
+- Font family and size configuration
+- Color schemes for different data types
+- Row highlighting and selection colors
+- Border and padding settings
+- Alignment options for columns
+
+**Section sources**
+- [HexDumpControl.axaml.cs:50-150](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L50-L150)
+- [HexDumpControl.axaml:100-200](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L100-L200)
+
+## Architecture Overview
+
+The HexDumpControl follows a modular architecture pattern that separates concerns between presentation, data binding, and business logic:
+
+```mermaid
+classDiagram
+class HexDumpControl {
+byte[] Data
+bool ShowAddress
+bool ShowAscii
+string AddressFormat
+FontFamily FontFamily
+Color ForegroundColor
+Color BackgroundColor
+event ClickHandler
+RenderHexDump()
+UpdateDisplay()
+HandleUserInteraction()
+}
+class PacketEntryBinaryValueConverter {
+Convert(byte[] value) string
+ConvertBack(string value) byte[]
+FormatHexBytes(byte[] data) string
+ValidateInput(object value) bool
+}
+class PacketEntryTextValueConverter {
+Convert(byte[] value) string
+ConvertBack(string value) byte[]
+FormatAsciiBytes(byte[] data) string
+IsPrintable(char c) bool
+}
+class DataBindingEngine {
+BindProperty(property, source)
+UnbindProperty(property)
+NotifyPropertyChanged(propertyName)
+}
+class RenderingEngine {
+DrawHexColumn(data, x, y)
+DrawAsciiColumn(data, x, y)
+DrawAddressColumn(offset, x, y)
+ApplyStyling(element, style)
+}
+HexDumpControl --> PacketEntryBinaryValueConverter : "uses"
+HexDumpControl --> PacketEntryTextValueConverter : "uses"
+HexDumpControl --> DataBindingEngine : "integrates with"
+HexDumpControl --> RenderingEngine : "renders via"
+PacketEntryBinaryValueConverter <|-- HexDumpControl : "extends"
+PacketEntryTextValueConverter <|-- HexDumpControl : "extends"
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml.cs:1-200](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L200)
+- [PacketEntryBinaryValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L100)
+- [PacketEntryTextValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L100)
+
+## Detailed Component Analysis
+
+### Data Binding and Conversion Pipeline
+
+The HexDumpControl implements a sophisticated data binding pipeline that handles the transformation of raw byte data into formatted display strings:
+
+```mermaid
+sequenceDiagram
+participant VM as "ViewModel"
+participant HDC as "HexDumpControl"
+participant BIN as "BinaryConverter"
+participant TXT as "TextConverter"
+participant UI as "UI Renderer"
+VM->>HDC : Set Data Property
+HDC->>BIN : Convert Bytes to Hex String
+BIN-->>HDC : Formatted Hex Data
+HDC->>TXT : Convert Bytes to ASCII String
+TXT-->>HDC : Formatted ASCII Data
+HDC->>UI : Render Display Elements
+UI-->>VM : Update Complete
+Note over VM,UI : Event Handling Flow
+UI->>HDC : User Click Event
+HDC->>HDC : Process Selection Logic
+HDC->>VM : Notify Property Change
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml.cs:100-250](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L100-L250)
+- [PacketEntryBinaryValueConverter.cs:50-150](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L50-L150)
+- [PacketEntryTextValueConverter.cs:50-150](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L50-L150)
+
+### Event Handling System
+
+The control implements comprehensive event handling for user interactions:
+
+#### Click Events
+- **Hex Value Click**: Selects individual byte values for copying or inspection
+- **ASCII Character Click**: Highlights corresponding byte positions
+- **Row Click**: Selects entire rows for batch operations
+- **Header Click**: Sorts or filters data based on column headers
+
+#### Keyboard Navigation
+- Arrow keys for navigation between cells
+- Space bar for selection toggling
+- Ctrl+C for copying selected data
+- Home/End keys for jumping to beginning/end of data
+
+#### Context Menu Integration
+- Copy selected data to clipboard
+- Export current view to file
+- Search within displayed data
+- Toggle display options dynamically
+
+**Section sources**
+- [HexDumpControl.axaml.cs:200-400](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L200-L400)
+- [HexDumpControl.axaml:150-300](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L150-L300)
+
+### XAML Usage Examples
+
+#### Basic Configuration
+```xml
+<controls:HexDumpControl 
+    Data="{Binding SelectedPacket.Data}"
+    ShowAddress="True"
+    ShowAscii="True"
+    AddressFormat="Hexadecimal"
+    FontFamily="Consolas"
+    FontSize="12"/>
+```
+
+#### Advanced Styling
+```xml
+<controls:HexDumpControl 
+    Data="{Binding LargeBinaryData}"
+    ShowAddress="True"
+    ShowAscii="False"
+    AddressFormat="Decimal"
+    ForegroundColor="#FF00FF00"
+    BackgroundColor="#FF1E1E1E"
+    HighlightColor="#FFFF0000"
+    FontFamily="Courier New"
+    FontSize="10"
+    RowHeight="20"
+    ColumnSpacing="5"/>
+```
+
+#### Dynamic Binding with Commands
+```xml
+<controls:HexDumpControl 
+    Data="{Binding CurrentPacket.Data}"
+    ShowAddress="{Binding ShowAddresses}"
+    ShowAscii="{Binding ShowAscii}"
+    AddressFormat="{Binding AddressFormatMode}"
+    ClickCommand="{Binding OnHexClick}">
+    <controls:HexDumpControl.Style>
+        <Style TargetType="controls:HexDumpControl">
+            <Setter Property="ThemeVariant" Value="Dark"/>
+            <Setter Property="BorderThickness" Value="1"/>
+            <Setter Property="Padding" Value="5"/>
+        </Style>
+    </controls:HexDumpControl.Style>
+</controls:HexDumpControl>
+```
+
+**Section sources**
+- [HexDumpControl.axaml:1-150](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L150)
+- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
+
+### C# Code-Behind Patterns
+
+#### Dynamic Data Binding
+```csharp
+// Initialize with empty data
+hexDumpControl.Data = new byte[0];
+
+// Bind to observable collection for real-time updates
+hexDumpControl.Data = packetObservableCollection;
+
+// Handle property changes
+hexDumpControl.PropertyChanged += (sender, e) => 
+{
+    if (e.PropertyName == nameof(HexDumpControl.Data))
+    {
+        UpdateStatistics();
+    }
+};
+```
+
+#### Event Handler Implementation
+```csharp
+private void OnHexValueClick(object sender, HexClickEventArgs e)
+{
+    var clickedByte = e.ByteValue;
+    var position = e.Position;
+    
+    // Perform custom logic for clicked byte
+    LogByteAnalysis(clickedByte, position);
+    HighlightRelatedBytes(position);
+}
+
+private void OnAsciiCharacterClick(object sender, AsciiClickEventArgs e)
+{
+    var character = e.Character;
+    var bytePosition = e.BytePosition;
+    
+    // Handle ASCII character interaction
+    ProcessCharacterInput(character, bytePosition);
+}
+```
+
+**Section sources**
+- [HexDumpControl.axaml.cs:300-500](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L300-L500)
+
+## Dependency Analysis
+
+The HexDumpControl has well-defined dependencies on external components and frameworks:
+
+```mermaid
+graph TD
+subgraph "External Dependencies"
+AVA[Avalonia UI Framework]
+CORE[.NET Runtime]
+DATA[System.Collections.Generic]
+IO[System.IO]
+end
+subgraph "Internal Dependencies"
+CONV[Value Converters]
+STYLE[Theme System]
+BIND[Data Binding]
+EVENT[Event System]
+end
+subgraph "Integration Points"
+PACKET[Packet Processing]
+LOG[Logging System]
+CLIP[Clipboard Service]
+FILE[File I/O]
+end
+HEXDUMP[HexDumpControl] --> AVA
+HEXDUMP --> CORE
+HEXDUMP --> DATA
+HEXDUMP --> IO
+HEXDUMP --> CONV
+HEXDUMP --> STYLE
+HEXDUMP --> BIND
+HEXDUMP --> EVENT
+HEXDUMP --> PACKET
+HEXDUMP --> LOG
+HEXDUMP --> CLIP
+HEXDUMP --> FILE
+CONV --> PACKET
+STYLE --> THEME[Theme Manager]
+BIND --> MODEL[Data Models]
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
+- [PacketEntryBinaryValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L50)
+- [PacketEntryTextValueConverter.cs:1-50](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L50)
+
+**Section sources**
+- [HexDumpControl.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L100)
+- [PacketEntryBinaryValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs#L1-L100)
+- [PacketEntryTextValueConverter.cs:1-100](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs#L1-L100)
+
+## Performance Considerations
+
+### Memory Management Strategies
+
+The HexDumpControl implements several strategies to handle large datasets efficiently:
+
+#### Virtualization Support
+- **Lazy Loading**: Only renders visible rows plus a buffer zone
+- **Object Pooling**: Reuses UI elements to minimize garbage collection pressure
+- **Memory Mapping**: Uses memory-mapped files for extremely large datasets
+
+#### Data Processing Optimization
+- **Chunked Processing**: Processes data in manageable chunks rather than loading entire datasets
+- **Background Threading**: Performs heavy computations on background threads
+- **Caching Layer**: Maintains cached representations of frequently accessed data segments
+
+#### Rendering Performance
+- **Hardware Acceleration**: Leverages GPU acceleration for text rendering where available
+- **Batch Updates**: Groups multiple property changes into single render cycles
+- **Selective Redraw**: Only updates changed portions of the display
+
+### Large Dataset Handling
+
+For datasets exceeding typical memory constraints:
+
+```mermaid
+flowchart TD
+Start([Large Dataset Received]) --> CheckSize["Check Dataset Size"]
+CheckSize --> |Small (< 1MB)| LoadAll["Load Entire Dataset"]
+CheckSize --> |Medium (1MB-100MB)| ChunkLoad["Load in Chunks"]
+CheckSize --> |Large (> 100MB)| StreamLoad["Stream from File"]
+LoadAll --> CacheData["Cache in Memory"]
+ChunkLoad --> CreateChunks["Create Chunk Manager"]
+StreamLoad --> SetupStream["Setup File Stream"]
+CacheData --> RenderOptimized["Render Optimized View"]
+CreateChunks --> RenderOptimized
+SetupStream --> RenderOptimized
+RenderOptimized --> MonitorMem["Monitor Memory Usage"]
+MonitorMem --> MemHigh{"Memory High?"}
+MemHigh --> |Yes| CleanupCache["Cleanup Unused Cache"]
+MemHigh --> |No| Continue["Continue Normal Operation"]
+CleanupCache --> Continue
+Continue --> End([Optimized Rendering])
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml.cs:400-600](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L400-L600)
+
+### Integration with Packet Logging and Debugging Tools
+
+The HexDumpControl integrates seamlessly with the application's packet logging system:
+
+#### Real-time Packet Inspection
+- **Live Updates**: Automatically refreshes when new packets arrive
+- **Filter Integration**: Supports filtering packets by type, direction, or content
+- **Search Functionality**: Enables searching within packet data streams
+
+#### Debugging Workflow Integration
+- **Breakpoint Support**: Allows setting breakpoints at specific byte positions
+- **Call Stack Correlation**: Links packet data to relevant code execution paths
+- **Export Capabilities**: Exports packet data in various formats for external analysis
+
+**Section sources**
+- [HexDumpControl.axaml.cs:500-700](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L500-L700)
+
+## Troubleshooting Guide
+
+### Common Issues and Solutions
+
+#### Performance Problems
+- **Symptom**: Slow rendering with large datasets
+- **Solution**: Enable virtualization and adjust chunk size settings
+- **Diagnostic**: Monitor memory usage and frame rates during operation
+
+#### Memory Leaks
+- **Symptom**: Increasing memory consumption over time
+- **Solution**: Ensure proper disposal of event handlers and data bindings
+- **Diagnostic**: Use memory profiling tools to identify leak sources
+
+#### Display Issues
+- **Symptom**: Incorrect character encoding or garbled ASCII output
+- **Solution**: Verify encoding settings and validate input data
+- **Diagnostic**: Test with known good data samples
+
+#### Event Handling Problems
+- **Symptom**: Click events not firing or incorrect position calculation
+- **Solution**: Check coordinate transformations and event routing
+- **Diagnostic**: Add debug logging for event coordinates and target elements
+
+### Debug Utilities
+
+The control includes built-in diagnostic capabilities:
+
+#### Performance Metrics
+- Frame rate monitoring
+- Memory allocation tracking
+- Rendering time measurement
+- Event processing latency
+
+#### Visual Debugging
+- Grid overlay for alignment verification
+- Coordinate system visualization
+- Hit testing indicators
+- Performance counters display
+
+**Section sources**
+- [HexDumpControl.axaml.cs:600-800](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L600-L800)
+
+## Conclusion
+
+The HexDumpControl represents a robust and feature-rich solution for binary data visualization within the ClassicAssist ecosystem. Its modular architecture, comprehensive event handling, and performance optimizations make it suitable for a wide range of debugging and analysis scenarios.
+
+Key strengths include:
+- Flexible configuration options for various display requirements
+- Efficient memory management for large datasets
+- Seamless integration with packet logging and debugging workflows
+- Extensive styling and customization capabilities
+- Comprehensive event handling for rich user interactions
+
+The component successfully balances usability with performance, providing developers with powerful tools for low-level data analysis while maintaining responsive user interfaces even with substantial data volumes.
+
+## Appendices
+
+### API Reference Summary
+
+#### Public Properties
+- `Data`: Primary data source for hex dump display
+- `ShowAddress`: Controls address column visibility
+- `ShowAscii`: Controls ASCII column visibility  
+- `AddressFormat`: Specifies address display format
+- `FontFamily`, `FontSize`: Typography settings
+- `ForegroundColor`, `BackgroundColor`: Color scheme configuration
+
+#### Events
+- `Click`: General click event handler
+- `HexValueClick`: Specific hex value click events
+- `AsciiCharClick`: ASCII character click events
+- `PropertyChanged`: Property change notifications
+
+#### Methods
+- `UpdateData(newData)`: Refresh display with new data
+- `Clear()`: Clear all displayed data
+- `ExportToFile(filePath)`: Save current view to file
+- `CopySelectedToClipboard()`: Copy selected data to clipboard
+
+**Section sources**
+- [HexDumpControl.axaml.cs:1-800](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs#L1-L800)
+- [HexDumpControl.axaml:1-400](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml#L1-L400)
@@ -0,0 +1,289 @@
+# HueEntryControl
+
+<cite>
+**Referenced Files in This Document**
+- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendices](#appendices)
+
+## Introduction
+This document provides comprehensive documentation for the HueEntryControl component used for color selection within the Ultima Online context. The control enables users to input a hue value, see an immediate visual preview, and validate that the value conforms to UO’s color system constraints. It supports both numeric entry and integration with a dedicated hue picker window, providing real-time updates to bound properties such as game object colors. The documentation covers properties, validation rules, interaction model, styling options, accessibility considerations, and practical examples for integrating with dress manager and autoloot systems.
+
+## Project Structure
+The HueEntryControl is implemented in the WPF UI layer and is consumed by various agent tabs (e.g., Dress and Autoloot). A companion HuePickerWindow provides a graphical color selection experience. An Avalonia-specific converter exists for rendering hue previews as rectangles.
+
+```mermaid
+graph TB
+subgraph "WPF UI"
+HEC["HueEntryControl<br/>xaml + code-behind"]
+HPW["HuePickerWindow<br/>xaml + code-behind"]
+DTC["DressTabControl"]
+ATC["AutolootTabControl"]
+end
+subgraph "Shared Data"
+HUES["UO Hues data"]
+end
+subgraph "Avalonia Helpers"
+CONV["HueEntryToRectanglesValueConverter"]
+end
+HEC --> HPW
+DTC --> HEC
+ATC --> HEC
+HEC --> HUES
+CONV -.-> HEC
+```
+
+**Diagram sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+
+**Section sources**
+- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+
+## Core Components
+- HueEntryControl: Provides a text box for numeric hue input, a color preview area, and optional integration with a hue picker dialog. Exposes properties for binding, including a validated hue value and validity state.
+- HuePickerWindow: A modal or non-modal window offering a visual palette for selecting hues; upon selection, it updates the bound hue value in the control.
+- DressTabControl and AutolootTabControl: Consume HueEntryControl to allow users to set item or rule colors.
+- HueEntryToRectanglesValueConverter: Converts hue values into visual rectangles for preview rendering in Avalonia contexts.
+- Hues: Shared data describing valid UO hues and related metadata.
+
+Key responsibilities:
+- Input handling and validation against UO hue constraints
+- Real-time preview updates
+- Integration with external hue picker
+- Binding support for consumer components
+
+**Section sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+
+## Architecture Overview
+The component follows a simple MVVM-friendly pattern:
+- HueEntryControl exposes bindable properties for HueValue and IsValid.
+- On user input changes, the control validates the value and updates IsValid and the preview.
+- When the hue picker is invoked, it returns a selected hue which the control binds back to HueValue.
+- Consumers (Dress and Autoloot tabs) bind to HueValue to apply colors to items or rules.
+
+```mermaid
+sequenceDiagram
+participant User as "User"
+participant HEC as "HueEntryControl"
+participant HPW as "HuePickerWindow"
+participant Consumer as "Dress/Autoloot Tab"
+User->>HEC : "Type numeric hue"
+HEC->>HEC : "Validate against UO constraints"
+HEC-->>Consumer : "Update HueValue and IsValid"
+HEC-->>User : "Real-time color preview"
+User->>HEC : "Open Hue Picker"
+HEC->>HPW : "Show picker"
+HPW-->>HEC : "Return selected hue"
+HEC->>HEC : "Set HueValue and re-validate"
+HEC-->>Consumer : "Update HueValue and IsValid"
+HEC-->>User : "Real-time color preview"
+```
+
+**Diagram sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+
+## Detailed Component Analysis
+
+### HueEntryControl Properties and Behavior
+- HueValue: The current hue value intended for use. Updated on input changes and after picker selection.
+- IsValid: Indicates whether the current HueValue satisfies UO constraints. Consumers should check this before applying colors.
+- Color Preview: Visual feedback showing the effective color corresponding to HueValue.
+- Validation Rules: Enforces UO-specific hue range and any additional constraints defined in shared data.
+
+Interaction model:
+- Numeric input: Users type a number; the control validates and updates preview immediately.
+- Hue picker: Users can open a picker window to select a hue visually; the chosen hue is written back to HueValue.
+- Real-time updates: Both input paths trigger validation and preview refresh.
+
+Styling and accessibility:
+- Preview area can be styled to ensure sufficient contrast.
+- For color-blind users, consider adding textual indicators (e.g., displaying the numeric hue next to the preview) and high-contrast themes.
+
+Integration points:
+- Consumers bind to HueValue and IsValid to conditionally enable actions or display errors.
+- Dress and Autoloot tabs demonstrate typical usage patterns.
+
+**Section sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HueEntryControl.xaml](file://ClassicAssist/UI/Controls/HueEntryControl.xaml)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+
+#### Class Diagram
+```mermaid
+classDiagram
+class HueEntryControl {
+int HueValue
+bool IsValid
+void OpenHuePicker()
+-void ValidateAndPreview()
+}
+class HuePickerWindow {
+void Show()
+int SelectedHue
+}
+class DressTabControl {
+bind HueValue
+bind IsValid
+}
+class AutolootTabControl {
+bind HueValue
+bind IsValid
+}
+class Hues {
+<<data>>
+}
+HueEntryControl --> HuePickerWindow : "opens"
+DressTabControl --> HueEntryControl : "consumes"
+AutolootTabControl --> HueEntryControl : "consumes"
+HueEntryControl --> Hues : "validates against"
+```
+
+**Diagram sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+
+### HuePickerWindow
+- Purpose: Provide a visual interface for selecting hues.
+- Behavior: Displays available hues; when a user selects one, the window communicates the chosen hue back to the caller (typically HueEntryControl).
+- Integration: Used by HueEntryControl to enhance usability beyond numeric entry.
+
+**Section sources**
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [HuePickerWindow.xaml](file://ClassicAssist/UI/Views/HuePickerWindow.xaml)
+
+### DressTabControl Usage Example
+- Demonstrates binding HueEntryControl to a dress rule’s color property.
+- Uses IsValid to prevent invalid colors from being applied.
+- Shows how to update the dress list preview when HueValue changes.
+
+**Section sources**
+- [DressTabControl.xaml](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+
+### AutolootTabControl Usage Example
+- Demonstrates binding HueEntryControl to autoloot rule conditions or item filters.
+- Validates hue inputs before enabling autoloot actions.
+- Integrates with existing autoloot configuration workflows.
+
+**Section sources**
+- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+
+### Avalonia Converter for Previews
+- HueEntryToRectanglesValueConverter converts hue values into rectangle visuals for preview rendering in Avalonia-based views.
+- Useful when building cross-platform UIs that need consistent hue previews.
+
+**Section sources**
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+
+## Dependency Analysis
+- HueEntryControl depends on:
+  - UO Hues data for validation constraints
+  - HuePickerWindow for visual selection
+  - Consumers (Dress/Autoloot tabs) for binding and application of colors
+- Avalonia converter is decoupled but can be used alongside HueEntryControl for preview rendering in Avalonia contexts.
+
+```mermaid
+graph LR
+HEC["HueEntryControl"] --> HUES["Hues"]
+HEC --> HPW["HuePickerWindow"]
+DTC["DressTabControl"] --> HEC
+ATC["AutolootTabControl"] --> HEC
+CONV["HueEntryToRectanglesValueConverter"] -.-> HEC
+```
+
+**Diagram sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+
+**Section sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
+- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+
+## Performance Considerations
+- Avoid excessive recomputation during rapid typing by debouncing validation if needed.
+- Keep preview updates lightweight; prefer direct brush updates rather than full layout passes.
+- Cache hue-to-color mappings where appropriate to reduce conversion overhead.
+
+[No sources needed since this section provides general guidance]
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- Invalid hue value: Ensure IsValid is checked before applying colors. Review UO hue constraints in shared data.
+- Preview not updating: Confirm bindings are two-way and that HueValue changes raise notifications.
+- Picker not returning value: Verify HuePickerWindow communication path and that the selected hue is assigned back to HueValue.
+- Accessibility concerns: Add textual hue labels and ensure sufficient contrast for color-blind users.
+
+**Section sources**
+- [HueEntryControl.xaml.cs](file://ClassicAssist/UI/Controls/HueEntryControl.xaml.cs)
+- [HuePickerWindow.xaml.cs](file://ClassicAssist/UI/Views/HuePickerWindow.xaml.cs)
+- [Hues.cs](file://ClassicAssist.Shared/UO/Data/Hues.cs)
+
+## Conclusion
+HueEntryControl offers a robust, user-friendly way to manage UO hue values with immediate visual feedback and strict validation. Its integration with HuePickerWindow enhances usability, while consumers like DressTabControl and AutolootTabControl demonstrate practical applications. By following the provided guidelines and leveraging the documented properties and behaviors, developers can implement reliable color selection experiences tailored to Ultima Online’s color system.
+
+[No sources needed since this section summarizes without analyzing specific files]
+
+## Appendices
+
+### Example Scenarios
+- Binding to a game object’s color: Bind HueValue to the object’s color property and use IsValid to guard updates.
+- Validating UO-specific hue values: Use the shared Hues data to enforce constraints and provide clear error feedback.
+- Integrating with dress manager: Use HueEntryControl in dress rules to let users pick item colors safely.
+- Integrating with autoloot systems: Apply hue validation to autoloot conditions to avoid invalid configurations.
+
+[No sources needed since this section provides conceptual examples]
@@ -0,0 +1,356 @@
+# TextBoxKey Control Documentation
+
+<cite>
+**Referenced Files in This Document**
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
+- [ShortcutKeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs)
+- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
+- [HotkeysTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml.cs)
+- [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendices](#appendices)
+
+## Introduction
+
+The TextBoxKey control is a specialized input control designed for capturing and displaying keyboard shortcuts and hotkey combinations in the ClassicAssist application. It provides an intuitive user interface for users to configure keyboard bindings, handling modifier keys (Ctrl, Alt, Shift), special keys, and complex key combinations while ensuring cross-platform compatibility and accessibility.
+
+This control serves as the primary interface for hotkey configuration throughout the application, allowing users to easily assign keyboard shortcuts to various commands and actions within the game client.
+
+## Project Structure
+
+The TextBoxKey control is implemented as part of the Avalonia UI framework integration, following modern MVVM patterns and leveraging Avalonia's cross-platform capabilities. The control consists of both markup and code-behind files that work together to provide a seamless user experience.
+
+```mermaid
+graph TB
+subgraph "Avalonia Controls"
+TK["TextBoxKey.axaml"]
+TKC["TextBoxKey.axaml.cs"]
+end
+subgraph "Shared Hotkey System"
+HM["HotkeyManager.cs"]
+SK["ShortcutKeys.cs"]
+HE["HotkeyEntry.cs"]
+end
+subgraph "UI Integration"
+HTC["HotkeysTabControl.axaml.cs"]
+HTVM["HotkeysTabViewModel.cs"]
+end
+TK --> TKC
+TKC --> HM
+TKC --> SK
+TKC --> HE
+HTC --> TK
+HTVM --> HM
+```
+
+**Diagram sources**
+- [TextBoxKey.axaml.cs:1-200](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L200)
+- [HotkeyManager.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L100)
+- [HotkeysTabControl.axaml.cs:1-150](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml.cs#L1-L150)
+
+**Section sources**
+- [TextBoxKey.axaml.cs:1-200](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L200)
+- [TextBoxKey.axaml:1-100](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml#L1-L100)
+
+## Core Components
+
+### TextBoxKey Control Properties
+
+The TextBoxKey control exposes several key properties that define its behavior and appearance:
+
+#### KeyBinding Property
+The primary property that stores the current key combination. This property supports both simple keys and complex combinations with modifiers.
+
+#### AllowModifiers Property
+A boolean flag that determines whether modifier keys (Ctrl, Alt, Shift) are allowed in the key combination. When set to false, only regular keys are accepted.
+
+#### IsRecording Property
+Indicates whether the control is currently capturing keyboard input for a new key binding.
+
+#### ValidationState Property
+Represents the current validation state of the entered key combination, including conflict detection results.
+
+### Keyboard Input Handling
+
+The control implements sophisticated keyboard event handling to capture and process user input:
+
+#### Modifier Key Detection
+- **Ctrl**: Detected through Ctrl key events and combined with other keys
+- **Alt**: Handled separately due to platform-specific behavior differences  
+- **Shift**: Processed along with other modifier combinations
+
+#### Special Key Support
+The control recognizes and properly displays special keys such as:
+- Function keys (F1-F12)
+- Navigation keys (Arrow keys, Home, End, Page Up/Down)
+- System keys (Escape, Tab, Enter, Backspace)
+- Media keys and multimedia functions
+
+#### International Keyboard Support
+The implementation accounts for different keyboard layouts and regional variations, ensuring consistent behavior across international setups.
+
+**Section sources**
+- [TextBoxKey.axaml.cs:50-150](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L50-L150)
+- [ShortcutKeys.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs#L1-L100)
+
+## Architecture Overview
+
+The TextBoxKey control follows a layered architecture pattern that separates concerns between UI presentation, input processing, and business logic:
+
+```mermaid
+sequenceDiagram
+participant User as "User"
+participant TK as "TextBoxKey Control"
+participant VM as "ViewModel"
+participant HM as "HotkeyManager"
+participant Config as "Configuration"
+User->>TK : Presses key combination
+TK->>TK : Capture keyboard event
+TK->>TK : Process modifiers and key
+TK->>HM : Validate key combination
+HM-->>TK : Validation result
+TK->>VM : Update KeyBinding property
+VM->>Config : Save to configuration
+Config-->>VM : Confirmation
+VM-->>TK : Update display
+```
+
+**Diagram sources**
+- [TextBoxKey.axaml.cs:100-200](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L100-L200)
+- [HotkeyManager.cs:50-150](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L50-L150)
+- [HotkeysTabViewModel.cs:1-100](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs#L1-L100)
+
+## Detailed Component Analysis
+
+### TextBoxKey Class Implementation
+
+The TextBoxKey class extends Avalonia's base control functionality to provide specialized keyboard input handling:
+
+#### Key Event Processing Flow
+
+```mermaid
+flowchart TD
+Start([Key Event Received]) --> CheckFocus{"Control Has Focus?"}
+CheckFocus --> |No| IgnoreEvent["Ignore Event"]
+CheckFocus --> |Yes| ProcessModifiers["Process Modifier Keys"]
+ProcessModifiers --> DetectKey["Detect Primary Key"]
+DetectKey --> ValidateCombination["Validate Key Combination"]
+ValidateCombination --> ConflictCheck{"Conflict Detected?"}
+ConflictCheck --> |Yes| ShowError["Display Error State"]
+ConflictCheck --> |No| UpdateBinding["Update KeyBinding Property"]
+ShowError --> UpdateDisplay["Update Visual State"]
+UpdateBinding --> UpdateDisplay
+UpdateDisplay --> NotifyVM["Notify ViewModel"]
+IgnoreEvent --> End([End])
+NotifyVM --> End
+```
+
+**Diagram sources**
+- [TextBoxKey.axaml.cs:150-250](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L150-L250)
+
+#### Display Formatting Logic
+
+The control implements intelligent formatting for displaying key combinations:
+
+- **Modifier Order**: Consistent ordering (Ctrl + Alt + Shift + Key)
+- **Special Key Names**: Human-readable names for function and system keys
+- **Platform Adaptation**: Platform-specific key name localization
+- **Visual Indicators**: Color coding for valid vs invalid combinations
+
+### Hotkey Management Integration
+
+The TextBoxKey control integrates seamlessly with the application's hotkey management system:
+
+#### Conflict Detection Algorithm
+
+```mermaid
+classDiagram
+class TextBoxKey {
+KeyBinding KeyBinding
+bool AllowModifiers
+bool IsRecording
+ValidationState ValidationState
+CaptureKey() void
+ClearBinding() void
+-ValidateCombination() bool
+-FormatKeyDisplay() string
+}
+class HotkeyManager {
+RegisterHotkey(KeyBinding) bool
+UnregisterHotkey(KeyBinding) bool
+HasConflict(KeyBinding) bool
+GetConflictingEntries(KeyBinding) HotkeyEntry[]
+SaveToConfiguration() void
+}
+class KeyBinding {
+Key Key
+bool Ctrl
+bool Alt
+bool Shift
+Equals(KeyBinding) bool
+ToString() string
+}
+class HotkeyEntry {
+string Name
+KeyBinding Binding
+Action Command
+bool IsActive
+}
+TextBoxKey --> HotkeyManager : "uses"
+TextBoxKey --> KeyBinding : "manages"
+HotkeyManager --> HotkeyEntry : "manages"
+HotkeyManager --> KeyBinding : "validates"
+```
+
+**Diagram sources**
+- [TextBoxKey.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L100)
+- [HotkeyManager.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L100)
+- [ShortcutKeys.cs:1-50](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs#L1-L50)
+
+### Cross-Platform Compatibility
+
+The control handles platform-specific keyboard behaviors:
+
+#### Windows-Specific Handling
+- Proper Alt key processing without triggering menu navigation
+- Correct handling of Windows key combinations
+- Unicode character support for international keyboards
+
+#### Linux/macOS Considerations
+- Super/Meta key mapping for command shortcuts
+- Different modifier key precedence rules
+- Application focus management for global hotkeys
+
+**Section sources**
+- [TextBoxKey.axaml.cs:200-300](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L200-L300)
+- [HotkeyManager.cs:100-200](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L100-L200)
+
+## Dependency Analysis
+
+The TextBoxKey control has well-defined dependencies on the shared hotkey infrastructure:
+
+```mermaid
+graph LR
+subgraph "UI Layer"
+TK["TextBoxKey Control"]
+HTC["HotkeysTabControl"]
+end
+subgraph "Business Logic"
+HM["HotkeyManager"]
+SK["ShortcutKeys"]
+end
+subgraph "Data Layer"
+HE["HotkeyEntry"]
+CFG["Configuration"]
+end
+TK --> HM
+TK --> SK
+HTC --> TK
+HM --> HE
+HM --> CFG
+SK --> HE
+```
+
+**Diagram sources**
+- [TextBoxKey.axaml.cs:1-50](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L50)
+- [HotkeyManager.cs:1-50](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L50)
+
+### Coupling and Cohesion Analysis
+
+The control maintains high cohesion by encapsulating all keyboard input logic within itself while maintaining loose coupling with external components through well-defined interfaces.
+
+**Section sources**
+- [TextBoxKey.axaml.cs:1-100](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L1-L100)
+- [HotkeyManager.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs#L1-L100)
+
+## Performance Considerations
+
+### Input Processing Optimization
+
+The control implements several performance optimizations:
+
+- **Debounced Input**: Prevents rapid successive key captures during modifier key sequences
+- **Efficient String Formatting**: Caches formatted key display strings to avoid repeated calculations
+- **Minimal Event Handlers**: Uses efficient event routing to reduce overhead
+- **Lazy Loading**: Defers expensive operations until needed
+
+### Memory Management
+
+- **Weak References**: Uses weak references for event handlers to prevent memory leaks
+- **Resource Cleanup**: Properly disposes of keyboard hooks and event subscriptions
+- **Garbage Collection Friendly**: Avoids creating unnecessary objects during normal operation
+
+## Troubleshooting Guide
+
+### Common Issues and Solutions
+
+#### Key Not Being Captured
+- Ensure the control has focus when pressing keys
+- Check if `AllowModifiers` is set appropriately
+- Verify that no other control is consuming the keyboard events
+
+#### Incorrect Display Format
+- Review the key combination for unsupported combinations
+- Check platform-specific limitations
+- Validate the key binding against the hotkey manager
+
+#### Conflict Detection Failures
+- Clear existing conflicting bindings before setting new ones
+- Verify hotkey manager initialization
+- Check for duplicate entries in configuration
+
+### Debugging Techniques
+
+Enable detailed logging by setting appropriate debug flags in the configuration. The control provides visual feedback through color changes and status messages to aid in debugging.
+
+**Section sources**
+- [TextBoxKey.axaml.cs:250-350](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs#L250-L350)
+
+## Conclusion
+
+The TextBoxKey control provides a robust, cross-platform solution for keyboard shortcut configuration in the ClassicAssist application. Its modular design, comprehensive error handling, and attention to accessibility make it a reliable component for managing user-defined hotkeys. The control successfully balances usability with technical complexity, providing an intuitive interface while maintaining clean separation of concerns and optimal performance.
+
+## Appendices
+
+### Accessibility Features
+
+The control includes several accessibility features:
+- **Screen Reader Support**: Proper announcements of key combinations
+- **Keyboard Navigation**: Full keyboard operability
+- **High Contrast Support**: Visual indicators for different states
+- **Focus Management**: Clear focus indicators and navigation
+
+### Configuration Examples
+
+Key bindings are typically stored in XML configuration files with the following structure:
+
+```xml
+<HotkeyEntry Name="ExampleCommand">
+  <KeyBinding>
+    <Key>F1</Key>
+    <Modifiers>Ctrl,Alt</Modifiers>
+  </KeyBinding>
+</HotkeyEntry>
+```
+
+### Best Practices
+
+When implementing custom key bindings:
+- Always validate combinations before saving
+- Provide clear user feedback for conflicts
+- Consider platform-specific conventions
+- Test with multiple keyboard layouts
+- Implement proper cleanup of hotkey registrations
@@ -0,0 +1,454 @@
+# Main Window and Navigation
+
+<cite>
+**Referenced Files in This Document**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs)
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml)
+- [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml)
+- [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml)
+- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml)
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Navigation System](#navigation-system)
+7. [Tab Management](#tab-management)
+8. [Responsive Design](#responsive-design)
+9. [Toolbar and Status Indicators](#toolbar-and-status-indicators)
+10. [Keyboard Shortcuts and Accessibility](#keyboard-shortcuts-and-accessibility)
+11. [Performance Considerations](#performance-considerations)
+12. [Troubleshooting Guide](#troubleshooting-guide)
+13. [Conclusion](#conclusion)
+
+## Introduction
+
+The ClassicAssist.Avalonia main window serves as the primary interface for users to interact with the Ultima Online assistant functionality. Built using Avalonia UI framework, it provides a modern, cross-platform desktop application experience with a tabbed interface organization that allows seamless navigation between different functional areas including Agents, Options, Macros, Skills, and Debug features.
+
+The main window implements a sophisticated navigation system that maintains application state across different views while providing responsive behavior across various screen sizes and resolutions. The interface is designed with accessibility in mind, supporting screen readers and alternative input methods to ensure inclusive user experience.
+
+## Project Structure
+
+The ClassicAssist.Avalonia application follows a clean MVVM (Model-View-ViewModel) architecture pattern typical of modern Avalonia applications. The main window implementation is organized into several key components:
+
+```mermaid
+graph TB
+subgraph "Main Application"
+App[App.axaml]
+Program[Program.cs]
+end
+subgraph "Main Window Layer"
+MainWindow[MainWindow.axaml]
+MainWindowVM[MainWindowViewModel.cs]
+end
+subgraph "Tab Controls"
+AgentsTab[AgentsTabControl.axaml]
+OptionsTab[OptionsTabControl.axaml]
+MacrosTab[MacrosTabControl.axaml]
+SkillsTab[SkillsTabControl.axaml]
+DebugWindow[DebugWindow.axaml]
+end
+subgraph "Shared ViewModels"
+SharedVM[Shared UI/ViewModels/]
+end
+App --> Program
+Program --> MainWindow
+MainWindow --> MainWindowVM
+MainWindow --> AgentsTab
+MainWindow --> OptionsTab
+MainWindow --> MacrosTab
+MainWindow --> SkillsTab
+MainWindow --> DebugWindow
+MainWindowVM --> SharedVM
+```
+
+**Diagram sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+
+## Core Components
+
+The main window interface consists of several core components that work together to provide a cohesive user experience:
+
+### Main Window Container
+The MainWindow serves as the root container for all UI elements, implementing proper window management, lifecycle handling, and integration with the Avalonia application framework.
+
+### Tab Control System
+A sophisticated tab control system manages the different functional areas, providing smooth transitions and maintaining state for each tab independently.
+
+### ViewModel Integration
+Each tab has its corresponding ViewModel that handles business logic, data binding, and user interactions, following the MVVM pattern for clean separation of concerns.
+
+### Resource Management
+Centralized resource management handles themes, icons, strings, and other shared resources across the application.
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+
+## Architecture Overview
+
+The ClassicAssist.Avalonia main window architecture follows a layered approach with clear separation between presentation, business logic, and data access layers:
+
+```mermaid
+classDiagram
+class MainWindow {
+TabControl MainTabControl
+StatusBar StatusBar
+ToolBar ToolBar
+InitializeComponent()
+OnLoaded()
+OnClosing()
+}
+class MainWindowViewModel {
+ObservableCollection~TabItem~ Tabs
+TabItem SelectedTab
+string Title
+bool IsLoading
+NavigateToTab(tabIndex)
+UpdateStatus(message)
+SaveWindowState()
+LoadWindowState()
+}
+class BaseTabViewModel {
+string TabTitle
+bool IsActive
+void OnActivate()
+void OnDeactivate()
+void Dispose()
+}
+class AgentsTabViewModel {
+ObservableCollection~AgentEntry~ Agents
+void AddAgent()
+void RemoveAgent()
+void EditAgent()
+}
+class OptionsTabViewModel {
+ObservableCollection~OptionEntry~ Options
+void SaveOptions()
+void ResetOptions()
+void ImportSettings()
+}
+class MacrosTabViewModel {
+ObservableCollection~MacroEntry~ Macros
+void ExecuteMacro()
+void StopMacro()
+void EditMacro()
+}
+class SkillsTabViewModel {
+ObservableCollection~SkillEntry~ Skills
+void UpdateSkillLock()
+void RefreshSkills()
+}
+MainWindow --> MainWindowViewModel : "binds to"
+MainWindowViewModel --> BaseTabViewModel : "manages"
+BaseTabViewModel <|-- AgentsTabViewModel
+BaseTabViewModel <|-- OptionsTabViewModel
+BaseTabViewModel <|-- MacrosTabViewModel
+BaseTabViewModel <|-- SkillsTabViewModel
+```
+
+**Diagram sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml)
+- [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml)
+- [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml)
+
+## Detailed Component Analysis
+
+### Main Window Layout Structure
+
+The main window layout is structured to provide optimal usability across different screen sizes and orientations. The layout includes:
+
+#### Header Section
+- Application title and version information
+- Quick access toolbar with frequently used actions
+- Status indicators showing connection status and current mode
+
+#### Navigation Area
+- Tab control with icons and labels for each functional area
+- Context menu support for right-click navigation
+- Keyboard shortcut indicators displayed in tab headers
+
+#### Content Area
+- Dynamic content panel that displays the active tab's content
+- Loading indicators during content initialization
+- Error handling and retry mechanisms for failed operations
+
+#### Footer Section
+- Status bar with detailed information
+- Progress indicators for long-running operations
+- Help and feedback quick access buttons
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+
+### Tabbed Interface Organization
+
+The tabbed interface provides intuitive navigation between different functional areas:
+
+#### Agents Tab
+Manages various agent types including autoloot, dress, friends, organizer, scavenger, and vendor agents. Each agent type has specific configuration options and monitoring capabilities.
+
+#### Options Tab
+Provides comprehensive application settings management including general options, hotkey configuration, network settings, and appearance customization.
+
+#### Macros Tab
+Offers macro creation, editing, and execution capabilities with syntax highlighting, command help, and debugging tools.
+
+#### Skills Tab
+Displays skill information, lock status management, and skill-based automation controls.
+
+#### Debug Tab
+Provides debugging tools, log viewers, packet inspection, and diagnostic information for troubleshooting.
+
+**Section sources**
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml)
+- [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml)
+- [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml)
+- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml)
+
+### Navigation Patterns
+
+The application implements multiple navigation patterns to accommodate different user preferences and workflows:
+
+#### Tab-Based Navigation
+Primary navigation method using the tab control with visual feedback for the active tab. Supports mouse clicks, keyboard navigation, and programmatic switching.
+
+#### Command-Based Navigation
+Quick access commands through toolbar buttons, context menus, and keyboard shortcuts for power users who prefer efficient workflows.
+
+#### State-Based Navigation
+Automatic navigation based on application events, such as opening debug window when errors occur or switching to macros tab when macro execution is requested.
+
+**Section sources**
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+
+## Navigation System
+
+The navigation system in ClassicAssist.Avalonia is built around a robust tab management architecture that ensures smooth user experience and proper state maintenance.
+
+### Tab Switching Mechanism
+
+The tab switching mechanism implements several key features:
+
+```mermaid
+sequenceDiagram
+participant User as "User"
+participant TabControl as "TabControl"
+participant VM as "MainWindowViewModel"
+participant ActiveTab as "Active Tab ViewModel"
+participant PreviousTab as "Previous Tab ViewModel"
+User->>TabControl : Click Tab
+TabControl->>VM : TabChanged Event
+VM->>PreviousTab : OnDeactivate()
+VM->>ActiveTab : OnActivate()
+VM->>VM : UpdateUIState()
+VM-->>TabControl : SetSelectedTab()
+TabControl-->>User : Display New Tab
+```
+
+**Diagram sources**
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+
+### Window State Management
+
+The application maintains comprehensive window state information:
+
+#### Position and Size Persistence
+- Window position, size, and maximized state are saved and restored automatically
+- Per-monitor DPI awareness ensures correct positioning across different displays
+- Responsive layout adapts to different screen sizes and orientations
+
+#### Tab State Preservation
+- Active tab selection is maintained across application restarts
+- Individual tab scroll positions and filter states are preserved
+- Temporary data and search queries are retained within session
+
+#### Theme and Appearance Settings
+- Dark/light theme switching with immediate effect
+- Custom color schemes and font scaling support
+- High-DPI display optimization
+
+**Section sources**
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+
+### Responsive Behavior
+
+The interface adapts seamlessly to different screen sizes and device characteristics:
+
+#### Adaptive Layout
+- Grid-based layout system adjusts column counts based on available width
+- Font sizes scale proportionally with DPI changes
+- Touch-friendly target sizes for tablet devices
+
+#### Performance Optimization
+- Lazy loading of tab content to improve startup performance
+- Virtualization for large lists and collections
+- Memory-efficient image and resource management
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+
+## Toolbar Functionality
+
+The toolbar provides quick access to frequently used functions and important controls:
+
+### Primary Toolbar Actions
+- **Connect/Disconnect**: Toggle game client connection status
+- **Start/Stop All**: Control macro execution globally
+- **Refresh**: Reload current tab content and update data
+- **Help**: Access contextual help and documentation
+- **Settings**: Open options dialog for application configuration
+
+### Contextual Actions
+- **Right-click Menu**: Additional options specific to current tab context
+- **Drag and Drop**: Reorder tabs and drag items between lists
+- **Hover Tooltips**: Descriptive tooltips for all toolbar buttons
+
+### Status Indicators
+- **Connection Status**: Visual indicator showing game client connectivity
+- **Macro Status**: Shows current macro execution state
+- **Error Notifications**: Warning and error message display
+- **Progress Indicators**: Animated progress bars for long operations
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+
+## Status Bar and Context Menus
+
+### Status Bar Features
+The status bar provides real-time application status and quick access information:
+
+- **Connection Status**: Shows UO client connection state with color coding
+- **Memory Usage**: Displays current memory consumption metrics
+- **FPS Counter**: Real-time frame rate monitoring for performance tuning
+- **Last Action**: Shows the most recent user action or system event
+- **Help Button**: Quick access to contextual help documentation
+
+### Context Menu Implementation
+Context menus provide additional functionality without cluttering the main interface:
+
+- **Tab Context Menu**: Close, close others, pin/unpin tabs
+- **List Context Menu**: Add, edit, delete, copy, paste operations
+- **Grid Context Menu**: Column customization, sorting, filtering options
+- **Property Context Menu**: Value editing, validation, and formatting tools
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+
+## Keyboard Shortcuts and Accessibility
+
+### Keyboard Navigation
+The application supports comprehensive keyboard navigation for power users and accessibility requirements:
+
+#### Global Shortcuts
+- **Ctrl+1-5**: Navigate to specific tabs (Agents, Options, Macros, Skills, Debug)
+- **Ctrl+T**: Open new tab or focus tab control
+- **Ctrl+W**: Close current tab
+- **Ctrl+F**: Focus search/filter functionality
+- **F1**: Open help documentation
+- **Alt+F4**: Close application
+
+#### Tab-Specific Shortcuts
+- **Agents Tab**: Ctrl+A (select all), Ctrl+C (copy), Ctrl+V (paste)
+- **Macros Tab**: F5 (execute), Shift+F5 (stop), Ctrl+E (edit)
+- **Options Tab**: Ctrl+S (save), Ctrl+R (reset), Ctrl+I (import)
+- **Skills Tab**: Space (toggle lock), Enter (edit details)
+
+#### Screen Reader Support
+- **ARIA Labels**: Comprehensive accessibility labels for all interactive elements
+- **Focus Management**: Logical tab order and focus trapping in dialogs
+- **Announcements**: Live region updates for dynamic content changes
+- **High Contrast**: Full high contrast theme support for visual impairments
+
+#### Alternative Input Methods
+- **Voice Control**: Compatible with Windows Speech Recognition
+- **Switch Control**: Full switch device compatibility
+- **Eye Tracking**: Point-and-click functionality for eye tracking devices
+- **Customizable Gestures**: Mouse gesture support for advanced users
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+
+## Performance Considerations
+
+### Memory Management
+- **Lazy Loading**: Tab content loads only when first accessed
+- **Resource Disposal**: Proper cleanup of images, fonts, and unmanaged resources
+- **Garbage Collection**: Optimized object pooling for frequently created objects
+
+### UI Responsiveness
+- **Background Processing**: Long-running operations execute on background threads
+- **Progressive Rendering**: UI updates incrementally for better perceived performance
+- **Virtual Scrolling**: Efficient rendering of large datasets
+
+### Startup Optimization
+- **Assembly Loading**: Deferred loading of optional assemblies
+- **Theme Initialization**: Lightweight default theme with deferred heavy processing
+- **Configuration Caching**: Cached configuration files to reduce disk I/O
+
+## Troubleshooting Guide
+
+### Common Issues and Solutions
+
+#### Tab Not Responding
+- **Symptom**: Tab appears frozen or unresponsive
+- **Solution**: Check background thread exceptions, verify data source availability
+- **Prevention**: Implement proper error handling and timeout mechanisms
+
+#### Memory Leaks
+- **Symptom**: Increasing memory usage over time
+- **Solution**: Review event handler subscriptions, check for circular references
+- **Prevention**: Use weak references for event handlers, implement proper disposal
+
+#### Performance Degradation
+- **Symptom**: Slow UI response or laggy scrolling
+- **Solution**: Enable virtualization, optimize data binding expressions
+- **Prevention**: Profile regularly, use appropriate collection types
+
+#### Accessibility Issues
+- **Symptom**: Screen reader not announcing content changes
+- **Solution**: Verify live regions are properly configured, check ARIA labels
+- **Prevention**: Test with multiple screen readers, follow WCAG guidelines
+
+### Debugging Tools
+- **Built-in Profiler**: Memory and CPU usage monitoring
+- **Log Viewer**: Centralized logging with filtering and export capabilities
+- **Network Inspector**: Packet flow analysis and debugging
+- **Hot Reload**: Development-time UI changes without restart
+
+**Section sources**
+- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
+
+## Conclusion
+
+The ClassicAssist.Avalonia main window and navigation system provides a comprehensive, accessible, and performant interface for managing Ultima Online gameplay assistance. The implementation demonstrates best practices in modern desktop application development, including proper MVVM architecture, responsive design principles, and comprehensive accessibility support.
+
+Key strengths of the implementation include:
+
+- **Modular Architecture**: Clean separation of concerns with well-defined interfaces
+- **Responsive Design**: Seamless adaptation to different screen sizes and DPI settings
+- **Accessibility Compliance**: Full support for assistive technologies and alternative input methods
+- **Performance Optimization**: Efficient resource management and lazy loading strategies
+- **User Experience**: Intuitive navigation patterns with multiple interaction methods
+
+The navigation system successfully balances simplicity for casual users with advanced features for power users, making it suitable for the diverse user base of the Ultima Online community. The implementation serves as an excellent example of modern Avalonia UI development practices and can serve as a reference for similar desktop application projects.
@@ -0,0 +1,443 @@
+# Theming and Styling System
+
+<cite>
+**Referenced Files in This Document**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
+- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
+- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendices](#appendices)
+
+## Introduction
+This document explains the theming and styling system used by ClassicAssist.Avalonia. It covers resource dictionaries, color schemes, font configurations, visual theme definitions, icon resources, dynamic theme switching, converters for data binding, and guidance for creating custom themes and platform-specific adaptations. The goal is to help you customize colors, fonts, and visual styles consistently across the application while maintaining performance and cross-platform compatibility.
+
+## Project Structure
+The Avalonia UI layer organizes theming and styling around Axaml files and C# code-behind:
+- Application entry points initialize the runtime and configure global resources.
+- Global resources (colors, icons, base styles) are defined in dedicated Axaml files under Assets and Controls.
+- Views reference resources via standard Axaml resource references and converters for value transformations.
+
+```mermaid
+graph TB
+Program["Program.cs"] --> AppAxaml["App.axaml"]
+AppAxaml --> AppCode["App.axaml.cs"]
+AppAxaml --> Icons["Assets/Icons.xaml"]
+AppAxaml --> GroupBoxTheme["Controls/GroupBox.Theme.xaml"]
+MainWindow["Views/MainWindow.axaml"] --> AppAxaml
+AboutControl["Views/AboutControl.axaml"] --> AppAxaml
+DialogWindow["Views/DialogWindow.axaml"] --> AppAxaml
+```
+
+**Diagram sources**
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+
+**Section sources**
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+
+## Core Components
+- Application bootstrap and resource initialization:
+  - Entry point sets up the Avalonia application and ensures resources are available at startup.
+  - App.axaml defines global resources and theme-related settings.
+  - App.axaml.cs contains any runtime configuration or programmatic resource adjustments.
+
+- Icon system:
+  - Centralized icon definitions are provided in an Axaml resource dictionary for reuse across views.
+
+- Control-level themes:
+  - Control-specific theme resources (e.g., GroupBox) are isolated in dedicated Axaml files for easy override and maintenance.
+
+- Converters for data binding:
+  - A set of value converters transform bound values into UI-friendly formats (strings, booleans, arrays, etc.).
+
+Key implementation locations:
+- Application bootstrap and resource setup: [Program.cs](file://ClassicAssist.Avalonia/Program.cs), [App.axaml](file://ClassicAssist.Avalonia/App.axaml), [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- Icons: [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- Control themes: [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- Converters: [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs), [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs), [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs), [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs), [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs), [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs), [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs), [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+
+**Section sources**
+- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
+- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
+- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+
+## Architecture Overview
+The theming architecture follows a layered approach:
+- Global resources define shared colors, fonts, and icons.
+- Control-level themes provide default appearances for specific controls.
+- Views consume resources and converters to render themed UIs.
+- Dynamic theme switching can be implemented by replacing or merging resource dictionaries at runtime.
+
+```mermaid
+graph TB
+subgraph "Global Resources"
+AppRes["App.axaml<br/>Global resources"]
+IconsRes["Assets/Icons.xaml<br/>Icon definitions"]
+end
+subgraph "Control Themes"
+GroupBoxTheme["Controls/GroupBox.Theme.xaml<br/>Control-specific styles"]
+end
+subgraph "Views"
+MainWindow["Views/MainWindow.axaml"]
+AboutControl["Views/AboutControl.axaml"]
+DialogWindow["Views/DialogWindow.axaml"]
+end
+AppRes --> MainWindow
+AppRes --> AboutControl
+AppRes --> DialogWindow
+IconsRes --> MainWindow
+IconsRes --> AboutControl
+IconsRes --> DialogWindow
+GroupBoxTheme --> MainWindow
+GroupBoxTheme --> AboutControl
+GroupBoxTheme --> DialogWindow
+```
+
+**Diagram sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+
+## Detailed Component Analysis
+
+### Resource Dictionary Structure and Loading
+- Global resources are declared in the application’s main Axaml file and referenced by views.
+- Icon resources are centralized in a dedicated Axaml file and included where needed.
+- Control-level themes are isolated in separate Axaml files to keep control appearance modular.
+
+Recommended structure:
+- Global colors and brushes: Define once in App.axaml for consistent usage across the app.
+- Fonts: Declare font families and sizes globally; override per-control if necessary.
+- Icons: Store reusable vector or image-based icons in Assets/Icons.xaml and reference by key.
+- Control themes: Place control-specific styles in Controls/*.Theme.xaml files.
+
+Resource loading mechanism:
+- At startup, the application initializes resources from App.axaml.
+- Views load resources through standard Axaml resource references.
+- For dynamic changes, replace or merge resource dictionaries programmatically in App.axaml.cs.
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+### Color Schemes and Visual Theme Definitions
+- Colors and brushes should be defined as global resources to ensure consistency.
+- Use semantic keys (e.g., primary, secondary, background, foreground) to simplify overrides.
+- Control themes can reference these semantic keys to adapt their appearance.
+
+Customization steps:
+- Add new color entries to the global resource dictionary.
+- Override existing brush keys in a theme-specific resource dictionary.
+- Apply theme dictionaries at runtime to switch palettes without rebuilding the UI.
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+### Font Configurations
+- Define font families and sizes in global resources for consistent typography.
+- Reference fonts in control themes and views using resource keys.
+- Provide fallback fonts for cross-platform compatibility.
+
+Platform considerations:
+- Ensure fonts are embedded or available on all target platforms.
+- Test rendering differences between Windows, macOS, and Linux.
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+### Icon System
+- Centralize icons in Assets/Icons.xaml for reuse across views.
+- Reference icons by key in Axaml bindings or style setters.
+- Keep icon assets optimized for performance and scalability.
+
+Usage patterns:
+- Bind icon properties to resource keys.
+- Use converters when transforming icon data for display.
+
+**Section sources**
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+
+### Dynamic Theme Switching
+- Implement runtime theme switching by replacing or merging resource dictionaries.
+- Maintain a mapping of theme names to resource dictionaries.
+- Trigger updates from user preferences or settings.
+
+Implementation outline:
+- In App.axaml.cs, expose methods to apply a theme by name.
+- Load the corresponding resource dictionary and update the application’s resources.
+- Notify UI components to refresh styles if necessary.
+
+**Section sources**
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+
+### Converter Classes for Data Binding and Value Transformation
+Converters bridge view models and UI elements by transforming data into presentation-ready formats.
+
+Key converters:
+- StringToResourceConverter: Resolves string keys to resource values.
+- InverseBooleanValueConverter: Flips boolean values for visibility toggles.
+- JoinArrayValueConverter: Concatenates array items into a single string.
+- DateTimeToTimeSpanValueConverter: Converts DateTime to TimeSpan for duration displays.
+- LockStatusValueConverter: Maps lock status enums to UI representations.
+- HueEntryToRectanglesValueConverter: Transforms hue entries into rectangle collections.
+- PacketEntryBinaryValueConverter: Formats binary packet data for display.
+- PacketEntryTextValueConverter: Formats text packet data for display.
+
+Usage examples:
+- Bind converter parameters to additional context or static resources.
+- Combine multiple converters using multi-value converters when needed.
+
+```mermaid
+classDiagram
+class StringToResourceConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+class InverseBooleanValueConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+class JoinArrayValueConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+class DateTimeToTimeSpanValueConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+class LockStatusValueConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+class HueEntryToRectanglesValueConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+class PacketEntryBinaryValueConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+class PacketEntryTextValueConverter {
+Convert(value, targetType, parameter, culture) object
+ConvertBack(value, targetType, parameter, culture) object
+}
+```
+
+**Diagram sources**
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
+- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
+- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+
+**Section sources**
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
+- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
+- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+
+### Creating Custom Themes
+Steps to create a custom theme:
+- Create a new Axaml resource dictionary with your color palette and font settings.
+- Override semantic resource keys to change appearance without modifying core styles.
+- Include the custom theme dictionary in App.axaml or load it dynamically.
+
+Best practices:
+- Use semantic keys for maintainability.
+- Keep theme dictionaries small and focused.
+- Test across platforms to ensure consistent rendering.
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+### Overriding Default Styles
+To override default control styles:
+- Define a new style for the control in a theme dictionary.
+- Set TargetType and Key to match the control and desired scope.
+- Reference the overriding style in your theme or view.
+
+Example pattern:
+- Create a style that targets a specific control and replaces setters for colors, fonts, and margins.
+- Ensure the style is loaded after the default theme to take precedence.
+
+**Section sources**
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+
+### Platform-Specific Visual Adaptations
+Guidelines:
+- Detect platform at runtime and adjust resources accordingly.
+- Provide alternative fonts or icons for better native feel.
+- Validate layout differences due to DPI scaling and window decorations.
+
+Implementation hints:
+- Use conditional logic in App.axaml.cs to load platform-specific resources.
+- Keep platform-specific styles in separate dictionaries for clarity.
+
+**Section sources**
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+
+## Dependency Analysis
+The theming system has clear dependencies:
+- Views depend on global resources and control themes.
+- Converters are referenced by views to transform data.
+- Application bootstrap initializes resources and may apply dynamic themes.
+
+```mermaid
+graph TB
+AppAxaml["App.axaml"] --> MainWindow["Views/MainWindow.axaml"]
+AppAxaml --> AboutControl["Views/AboutControl.axaml"]
+AppAxaml --> DialogWindow["Views/DialogWindow.axaml"]
+Icons["Assets/Icons.xaml"] --> MainWindow
+Icons --> AboutControl
+Icons --> DialogWindow
+GroupBoxTheme["Controls/GroupBox.Theme.xaml"] --> MainWindow
+GroupBoxTheme --> AboutControl
+GroupBoxTheme --> DialogWindow
+Converters["Misc/*ValueConverter.cs"] --> MainWindow
+Converters --> AboutControl
+Converters --> DialogWindow
+```
+
+**Diagram sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
+- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
+- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [DateTimeToTimeSpanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/DateTimeToTimeSpanValueConverter.cs)
+- [LockStatusValueConverter.cs](file://ClassicAssist.Avalonia/Misc/LockStatusValueConverter.cs)
+- [HueEntryToRectanglesValueConverter.cs](file://ClassicAssist.Avalonia/Misc/HueEntryToRectanglesValueConverter.cs)
+- [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs)
+- [PacketEntryTextValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryTextValueConverter.cs)
+
+## Performance Considerations
+- Prefer static resources over dynamic bindings for frequently used colors and fonts.
+- Minimize converter complexity; precompute results when possible.
+- Avoid excessive resource dictionary merges at runtime; batch updates.
+- Use vector icons where feasible to reduce memory footprint and improve scaling.
+- Profile UI rendering when applying heavy themes to identify bottlenecks.
+
+[No sources needed since this section provides general guidance]
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- Missing resource keys: Ensure all referenced keys exist in global or local resource dictionaries.
+- Incorrect converter parameters: Verify converter bindings and parameter types.
+- Theme not applied: Confirm the theme dictionary is loaded and merged after defaults.
+- Cross-platform inconsistencies: Check font availability and DPI scaling behavior.
+
+Debugging tips:
+- Inspect resource resolution order in Axaml.
+- Log converter inputs and outputs during development.
+- Use minimal reproducible examples to isolate theme conflicts.
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+
+## Conclusion
+The ClassicAssist.Avalonia theming system leverages Axaml resource dictionaries, centralized icons, and control-level themes to deliver a flexible and maintainable UI. By defining semantic resources, using converters judiciously, and implementing dynamic theme switching, you can create cohesive, customizable, and performant interfaces across platforms. Follow the guidelines above to extend themes, override styles, and adapt visuals for different environments.
+
+[No sources needed since this section summarizes without analyzing specific files]
+
+## Appendices
+
+### Quick Start: Applying a Custom Theme
+- Create a new Axaml resource dictionary with your theme colors and fonts.
+- Add the dictionary to App.axaml or load it in App.axaml.cs.
+- Reference semantic resource keys in views and control themes.
+- Test on all target platforms and adjust as needed.
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
@@ -0,0 +1,620 @@
+# User Interface Guide
+
+<cite>
+**Referenced Files in This Document**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs)
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs)
+- [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+- [DialogWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml.cs)
+- [DialogWindowViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/DialogWindowViewModel.cs)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [AgentsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml.cs)
+- [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml)
+- [HotkeysTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml.cs)
+- [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml)
+- [MacrosTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs)
+- [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml)
+- [OptionsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml.cs)
+- [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml)
+- [SkillsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml.cs)
+- [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml)
+- [GeneralControl.axaml.cs](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml.cs)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [AboutControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AboutControl.axaml.cs)
+- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml)
+- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml.cs)
+- [HuePickerWindow.axaml](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml)
+- [HuePickerWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml.cs)
+- [NewProfileWindow.axaml](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml)
+- [NewProfileWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml.cs)
+- [ObjectInspectorWindow.axaml](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml)
+- [ObjectInspectorWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml.cs)
+- [AutolootTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/AutolootTabControl.axaml)
+- [CountersTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/CountersTabControl.axaml)
+- [DressTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.axaml)
+- [FriendsTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/FriendsTabControl.axaml)
+- [OrganizerTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/OrganizerTabControl.axaml)
+- [ScavengerTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
+- [VendorBuyTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml)
+- [VendorSellTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs)
+- [CloseOnClickBehaviour.cs](file://ClassicAssist.Avalonia/Misc/CloseOnClickBehaviour.cs)
+- [ComboBoxBehavior.cs](file://ClassicAssist.Avalonia/Misc/ComboBoxBehavior.cs)
+- [WindowInitializedBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowInitializedBehaviour.cs)
+- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
+- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
+</cite>
+
+## Table of Contents
+1. Introduction
+2. Project Structure
+3. Core Components
+4. Architecture Overview
+5. Detailed Component Analysis
+6. Dependency Analysis
+7. Performance Considerations
+8. Troubleshooting Guide
+9. Conclusion
+10. Appendices
+
+## Introduction
+This guide documents the Avalonia-based user interface for ClassicAssist.Avalonia. It explains the main window layout, tabbed navigation, control hierarchy (including HexDumpControl, EditTextBlock, and TextBoxKey), theming and customization, keyboard shortcuts and accessibility, responsive design considerations, cross-platform UI differences, MVVM binding patterns, and how to extend or customize existing UI elements.
+
+## Project Structure
+The Avalonia UI is organized into Views, Controls, ViewModels, and shared resources:
+- Views: Top-level windows and reusable page-like controls (e.g., MainWindow, DialogWindow, tab controls).
+- Controls: Custom reusable components (e.g., HexDumpControl, EditTextBlock, TextBoxKey, GroupBox).
+- ViewModels: Presentation logic bound to views via data binding.
+- Resources: Theme definitions, icons, and converters.
+
+```mermaid
+graph TB
+subgraph "Avalonia App"
+App["App.axaml"]
+MainWin["Views/MainWindow.axaml"]
+Tabs["Views/*TabControl.axaml"]
+Dialog["Views/DialogWindow.axaml"]
+end
+subgraph "Custom Controls"
+Hex["Controls/HexDumpControl.axaml"]
+EditTxt["Controls/EditTextBlock.axaml"]
+TxtKey["Controls/TextBoxKey.axaml"]
+Grp["Controls/GroupBox.cs + .Theme.xaml"]
+end
+subgraph "Behaviours & Converters"
+Beh["Misc/*Behaviour.cs"]
+Conv["Misc/*ValueConverter.cs"]
+end
+App --> MainWin
+MainWin --> Tabs
+MainWin --> Dialog
+Tabs --> Hex
+Tabs --> EditTxt
+Tabs --> TxtKey
+Tabs --> Grp
+Tabs --> Beh
+Tabs --> Conv
+```
+
+**Diagram sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs)
+- [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+
+**Section sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+
+## Core Components
+- Main Window: Hosts a tabbed interface and provides global commands and status.
+- Tab Controls: Feature-specific tabs (Agents, Hotkeys, Macros, Options, Skills, General, About).
+- Custom Controls:
+  - HexDumpControl: Binary/hex viewer with scrolling and selection.
+  - EditTextBlock: Read-only text block with optional editing affordances.
+  - TextBoxKey: Key capture input for hotkey bindings.
+  - GroupBox: Themed container for grouping related controls.
+- Behaviours: Reusable interactions attached to controls (auto-scroll, resize, combo box behavior).
+- Converters: Value conversions used in bindings (boolean inversion, string joining, resource lookup).
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml)
+- [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml)
+- [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml)
+- [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml)
+- [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+- [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs)
+- [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+
+## Architecture Overview
+The UI follows MVVM:
+- Views (AXAML) bind to ViewModels through DataContext.
+- Behaviours encapsulate view-side interactions without code-behind logic.
+- Converters adapt model values for display.
+- Theming and icons are centralized in resource dictionaries.
+
+```mermaid
+sequenceDiagram
+participant User as "User"
+participant Win as "MainWindow.axaml"
+participant Tab as "AgentsTabControl.axaml"
+participant VM as "AgentsTabControl ViewModel"
+participant Ctrl as "HexDumpControl.axaml"
+participant Beh as "ListBoxAutoScrollBehaviour.cs"
+User->>Win : Open app
+Win->>Tab : Load selected tab
+Tab->>VM : Bind properties and collections
+Tab->>Ctrl : Render hex dump
+Ctrl->>Beh : Auto-scroll on update
+VM-->>Tab : Update UI via INotifyPropertyChanged
+```
+
+**Diagram sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs)
+
+## Detailed Component Analysis
+
+### Main Window Layout and Navigation
+- The main window hosts a tabbed interface that switches between feature areas such as Agents, Hotkeys, Macros, Options, Skills, General, and About.
+- Navigation is driven by selecting a tab; each tab loads its corresponding view and binds to a dedicated ViewModel.
+- Global actions (e.g., opening dialogs or debug windows) are exposed from the main window’s ViewModel and invoked via commands.
+
+```mermaid
+flowchart TD
+Start(["App Launch"]) --> Init["Initialize App.axaml"]
+Init --> ShowMain["Show MainWindow.axaml"]
+ShowMain --> SelectTab{"User selects tab?"}
+SelectTab --> |Yes| LoadTab["Load selected Tab Control"]
+LoadTab --> BindVM["Bind to Tab ViewModel"]
+BindVM --> Render["Render controls and lists"]
+SelectTab --> |No| Idle["Keep current tab"]
+Render --> End(["Ready"])
+Idle --> End
+```
+
+**Diagram sources**
+- [App.axaml](file://ClassicAssist.Avalonia/App.axaml)
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+
+### Tabbed Interface Structure
+- Agents: Sub-tabs for Autoloot, Counters, Dress, Friends, Organizer, Scavenger, Vendor Buy, Vendor Sell.
+- Hotkeys: Configure key bindings and commands.
+- Macros: Manage macro entries and execution.
+- Options: Application-wide settings.
+- Skills: Skill management and locks.
+- General and About: Informational pages.
+
+```mermaid
+classDiagram
+class MainWindow {
+Tabs
+Commands
+}
+class AgentsTabControl
+class HotkeysTabControl
+class MacrosTabControl
+class OptionsTabControl
+class SkillsTabControl
+class GeneralControl
+class AboutControl
+MainWindow --> AgentsTabControl : "hosts"
+MainWindow --> HotkeysTabControl : "hosts"
+MainWindow --> MacrosTabControl : "hosts"
+MainWindow --> OptionsTabControl : "hosts"
+MainWindow --> SkillsTabControl : "hosts"
+MainWindow --> GeneralControl : "hosts"
+MainWindow --> AboutControl : "hosts"
+```
+
+**Diagram sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml)
+- [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml)
+- [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml)
+- [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml)
+- [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+
+**Section sources**
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [HotkeysTabControl.axaml](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml)
+- [MacrosTabControl.axaml](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml)
+- [OptionsTabControl.axaml](file://ClassicAssist.Avalonia/Views/OptionsTabControl.axaml)
+- [SkillsTabControl.axaml](file://ClassicAssist.Avalonia/Views/SkillsTabControl.axaml)
+- [GeneralControl.axaml](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml)
+- [AboutControl.axaml](file://ClassicAssist.Avalonia/Views/AboutControl.axaml)
+
+### Control Hierarchy and Custom Controls
+
+#### HexDumpControl
+- Purpose: Display binary data in hexadecimal and ASCII formats with efficient scrolling.
+- Key behaviors:
+  - Virtualized rendering for large datasets.
+  - Selection and copy support.
+  - Optional auto-scroll when new data arrives.
+- Integration points:
+  - Used within agent-related tabs and debug views.
+  - Enhanced by behaviours like auto-scroll.
+
+```mermaid
+classDiagram
+class HexDumpControl {
+Data
+SelectedRange
+AutoScroll
+CopySelection()
+}
+class ListBoxAutoScrollBehaviour {
+Attach(control)
+OnCollectionChanged()
+}
+HexDumpControl --> ListBoxAutoScrollBehaviour : "uses"
+```
+
+**Diagram sources**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs)
+
+**Section sources**
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs)
+- [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs)
+
+#### EditTextBlock
+- Purpose: Rich read-only text display with optional editing affordances.
+- Features:
+  - Syntax highlighting integration via AvalonEdit behaviour.
+  - Copy-to-clipboard support.
+  - Scrollable content with performance optimizations.
+- Typical usage: Log viewers, property inspectors, and macro output.
+
+```mermaid
+classDiagram
+class EditTextBlock {
+Text
+IsEditable
+HighlightMode
+}
+class AvalonEditBehaviour {
+Attach(editor)
+SetLanguage(mode)
+}
+EditTextBlock --> AvalonEditBehaviour : "enhances"
+```
+
+**Diagram sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs)
+
+**Section sources**
+- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
+- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
+- [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs)
+
+#### TextBoxKey
+- Purpose: Capture and display key combinations for hotkey configuration.
+- Behavior:
+  - Listens to key events and formats them into readable strings.
+  - Supports modifier keys and special keys.
+  - Validates and prevents duplicate bindings at the UI layer.
+- Integration:
+  - Used in Hotkeys tab and other configuration surfaces.
+
+```mermaid
+flowchart TD
+Enter(["KeyDown Event"]) --> Detect["Detect modifiers and key"]
+Detect --> Format["Format key string"]
+Format --> Validate{"Duplicate binding?"}
+Validate --> |Yes| Warn["Show warning"]
+Validate --> |No| Bind["Update bound value"]
+Warn --> Exit(["Done"])
+Bind --> Exit
+```
+
+**Diagram sources**
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+
+**Section sources**
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+
+#### GroupBox
+- Purpose: Themed container for grouping related controls.
+- Customization:
+  - Style defined in theme dictionary.
+  - Extensible header and content regions.
+
+```mermaid
+classDiagram
+class GroupBox {
+Header
+Content
+}
+class GroupBoxTheme {
+Styles
+Templates
+}
+GroupBox --> GroupBoxTheme : "styled by"
+```
+
+**Diagram sources**
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+**Section sources**
+- [GroupBox.cs](file://ClassicAssist.Avalonia/Controls/GroupBox.cs)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+### Theming System
+- Centralized resources include colors, icons, and styles.
+- Icons are provided via a resource dictionary for consistent visual language across the app.
+- Themes can be extended by adding or overriding resource entries.
+
+```mermaid
+graph TB
+Res["Resources (Colors, Icons)"]
+Styles["Styles and Templates"]
+Controls["Custom Controls"]
+Views["Views"]
+Res --> Styles
+Styles --> Controls
+Styles --> Views
+Controls --> Views
+```
+
+**Diagram sources**
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+**Section sources**
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+- [GroupBox.Theme.xaml](file://ClassicAssist.Avalonia/Controls/GroupBox.Theme.xaml)
+
+### Keyboard Shortcuts and Accessibility
+- Hotkey capture is handled by TextBoxKey, which formats and validates key combinations.
+- Global toggles and commands are typically exposed via menu items or toolbar buttons bound to commands in ViewModels.
+- Accessibility:
+  - Use standard Avalonia controls to inherit platform accessibility features.
+  - Ensure meaningful labels and tool tips for custom controls.
+
+**Section sources**
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [TextBoxKey.axaml.cs](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml.cs)
+
+### Responsive Design and Cross-Platform Considerations
+- Responsive behaviors:
+  - WindowResizeBehaviour adapts layouts on size changes.
+  - Auto-scroll behaviours improve usability for long lists and logs.
+- Platform differences:
+  - Font rendering and icon scaling may vary across platforms; use scalable vector icons where possible.
+  - Input handling (keyboard/mouse) is abstracted by Avalonia but may exhibit minor differences in key mapping.
+
+```mermaid
+flowchart TD
+Resize["Window resized"] --> Measure["Measure available space"]
+Measure --> Adjust["Adjust column widths and scrollbars"]
+Adjust --> Update["Rebind and re-render"]
+```
+
+**Diagram sources**
+- [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs)
+
+**Section sources**
+- [WindowResizeBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowResizeBehaviour.cs)
+- [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs)
+
+### MVVM Binding Patterns and Extensibility
+- Data binding:
+  - Views bind to properties and collections in ViewModels using Avalonia’s binding syntax.
+  - Converters transform values (e.g., boolean inversion, array joining, resource lookup).
+- Commands:
+  - Actions are implemented as commands in ViewModels and invoked from XAML.
+- Extending UI elements:
+  - Create new custom controls by extending existing ones (e.g., HexDumpControl).
+  - Add behaviours for reusable interactions (e.g., auto-scroll, click-to-close).
+  - Provide converters for complex formatting needs.
+
+```mermaid
+sequenceDiagram
+participant V as "View (XAML)"
+participant VM as "ViewModel"
+participant C as "Converter"
+participant B as "Behaviour"
+V->>VM : Bind Property
+VM-->>V : PropertyChanged
+V->>C : Convert(value)
+C-->>V : Converted value
+V->>B : Attach interaction
+B-->>V : Handle events
+```
+
+**Diagram sources**
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [CloseOnClickBehaviour.cs](file://ClassicAssist.Avalonia/Misc/CloseOnClickBehaviour.cs)
+- [ComboBoxBehavior.cs](file://ClassicAssist.Avalonia/Misc/ComboBoxBehavior.cs)
+- [WindowInitializedBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowInitializedBehaviour.cs)
+
+**Section sources**
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [JoinArrayValueConverter.cs](file://ClassicAssist.Avalonia/Misc/JoinArrayValueConverter.cs)
+- [StringToResourceConverter.cs](file://ClassicAssist.Avalonia/Misc/StringToResourceConverter.cs)
+- [CloseOnClickBehaviour.cs](file://ClassicAssist.Avalonia/Misc/CloseOnClickBehaviour.cs)
+- [ComboBoxBehavior.cs](file://ClassicAssist.Avalonia/Misc/ComboBoxBehavior.cs)
+- [WindowInitializedBehaviour.cs](file://ClassicAssist.Avalonia/Misc/WindowInitializedBehaviour.cs)
+
+### Dialogs and Modal Windows
+- DialogWindow provides a reusable modal dialog pattern with a ViewModel for state and commands.
+- Common uses: confirmations, prompts, and small configuration panels.
+
+```mermaid
+sequenceDiagram
+participant Caller as "Caller ViewModel"
+participant Win as "DialogWindow.axaml"
+participant VM as "DialogWindowViewModel"
+Caller->>Win : ShowDialog()
+Win->>VM : Initialize with parameters
+VM-->>Caller : Result on close
+```
+
+**Diagram sources**
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+- [DialogWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml.cs)
+- [DialogWindowViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/DialogWindowViewModel.cs)
+
+**Section sources**
+- [DialogWindow.axaml](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml)
+- [DialogWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DialogWindow.axaml.cs)
+- [DialogWindowViewModel.cs](file://ClassicAssist.Avalonia/ViewModels/DialogWindowViewModel.cs)
+
+### Specialized Windows
+- DebugWindow: Diagnostic tools and live data inspection.
+- HuePickerWindow: Color selection utility.
+- NewProfileWindow: Profile creation workflow.
+- ObjectInspectorWindow: Inspect runtime objects and properties.
+
+```mermaid
+graph TB
+Main["MainWindow"]
+Debug["DebugWindow.axaml"]
+Hue["HuePickerWindow.axaml"]
+NewProf["NewProfileWindow.axaml"]
+Insp["ObjectInspectorWindow.axaml"]
+Main --> Debug
+Main --> Hue
+Main --> NewProf
+Main --> Insp
+```
+
+**Diagram sources**
+- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml)
+- [HuePickerWindow.axaml](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml)
+- [NewProfileWindow.axaml](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml)
+- [ObjectInspectorWindow.axaml](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml)
+
+**Section sources**
+- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml)
+- [HuePickerWindow.axaml](file://ClassicAssist.Avalonia/Views/HuePickerWindow.axaml)
+- [NewProfileWindow.axaml](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml)
+- [ObjectInspectorWindow.axaml](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml)
+
+## Dependency Analysis
+- UI layer depends on ViewModels for state and commands.
+- Custom controls depend on behaviours and converters for enhanced functionality.
+- Theming resources are consumed by controls and views.
+
+```mermaid
+graph LR
+Views["Views"] --> VMs["ViewModels"]
+Views --> Controls["Custom Controls"]
+Controls --> Behaviours["Behaviours"]
+Controls --> Converters["Converters"]
+Views --> Resources["Themes & Icons"]
+```
+
+**Diagram sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+
+**Section sources**
+- [MainWindow.axaml](file://ClassicAssist.Avalonia/Views/MainWindow.axaml)
+- [AgentsTabControl.axaml](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml)
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [AvalonEditBehaviour.cs](file://ClassicAssist.Avalonia/Misc/AvalonEditBehaviour.cs)
+- [InverseBooleanValueConverter.cs](file://ClassicAssist.Avalonia/Misc/InverseBooleanValueConverter.cs)
+- [Icons.xaml](file://ClassicAssist.Avalonia/Assets/Icons.xaml)
+
+## Performance Considerations
+- Use virtualized lists and grids for large datasets.
+- Prefer lazy loading of heavy content in tabs.
+- Avoid excessive UI updates; batch changes in ViewModels.
+- Leverage auto-scroll behaviours judiciously to prevent jank during rapid updates.
+
+[No sources needed since this section provides general guidance]
+
+## Troubleshooting Guide
+- UI not updating:
+  - Ensure ViewModels implement property change notifications.
+  - Verify bindings target correct paths and converters are applied.
+- Hotkey conflicts:
+  - Check TextBoxKey validation and ensure duplicates are prevented.
+- Slow rendering:
+  - Confirm virtualization is enabled for large lists.
+  - Reduce unnecessary bindings and heavy operations in UI thread.
+
+**Section sources**
+- [TextBoxKey.axaml](file://ClassicAssist.Avalonia/Controls/TextBoxKey.axaml)
+- [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml)
+- [ListBoxAutoScrollBehaviour.cs](file://ClassicAssist.Avalonia/Misc/ListBoxAutoScrollBehaviour.cs)
+
+## Conclusion
+The ClassicAssist.Avalonia UI leverages a clean MVVM architecture, reusable custom controls, and centralized theming to deliver a consistent, extensible experience across platforms. By following the patterns outlined here—using behaviours for interactions, converters for formatting, and ViewModels for state—you can confidently extend and customize the interface while maintaining performance and accessibility.
+
+[No sources needed since this section summarizes without analyzing specific files]
+
+## Appendices
+
+### Screenshots and Visual Guides
+- Main Window: Shows the primary tabbed interface and global commands.
+- Agents Tab: Displays sub-tabs for various agents and their configurations.
+- Hex Dump Viewer: Demonstrates binary data visualization and selection.
+- Hotkeys Tab: Illustrates key capture and binding management.
+- Dialog Window: Example of modal interactions and confirmation flows.
+
+[No sources needed since this section provides conceptual guidance]