Namespace SharpConsoleUI.Helpers

AllocationGuard: Guards against integer overflow and unbounded allocations when computing buffer sizes from potentially untrusted dimensions. Use this whenever allocating arrays whose size derives from external input (image dimensions, video frame sizes, terminal coordinates from protocol responses).

BrailleHelpers: Shared static helpers for pixel-grid braille rendering. Provides Bresenham's line algorithm and braille character mapping for controls that render using Unicode Braille patterns (U+2800 block).

ClipboardHelper: Cross-platform clipboard helper for console applications. On Linux tries wl-clipboard, xclip, xsel. Falls back to an in-process buffer when no external tool is available. Operations are best-effort and will not throw on failure.

ColorBlendHelper: Shared color blending utilities used by flash overlay, fade animations, and other effects. Extracted to avoid code duplication between WindowStateService and WindowAnimations.

ColorGradient: Helper for creating and interpolating smooth color gradients. Supports predefined gradients (cool, warm, spectrum, grayscale) and custom gradients.

ColorResolver: Provides centralized color resolution logic for controls. Resolution chain: explicit value → theme slot → Color.Transparent. null and Color.Default are treated identically (both mean "no explicit value").

ColorRoleResolver: Derives a coordinated ColorRoleSet set from a single ColorRole, using per-theme seed colours (theme.PrimaryColor and friends) with a fall back to built-in defaults, plus the two non-null theme anchors. Pure and reflection-free — the single derivation brain shared by controls and the palette theme generator.

ContentHelper: Provides helper methods for content layout and positioning calculations.

ControlRenderingHelpers: Shared rendering utilities for controls to avoid code duplication. Pass Transparent as background to preserve whatever is already in the buffer (gradient, parent background, etc.).

DragAutoScroll: Pure step computation for drag-select autoscroll. Given the cursor's control-relative Y, the viewport height in rows, and the frame's elapsed time, returns the signed number of rows to scroll this frame. Distance-accelerated and time-normalized, with a fractional carry so speed stays smooth at any frame rate. No clock, no threads — fully unit-testable.

ExceptionFormatter: Writes ANSI-colored exception output to a TextWriter, replacing Spectre.Console's AnsiConsole.WriteException with zero external dependencies. Intended for crash-time reporting after Console.Clear().

GeometryHelpers: Provides static helper methods for Rectangle geometry operations. Extracted from ConsoleWindowSystem as part of Phase 3.1 refactoring. Consolidates duplicate geometry logic from multiple classes.

LinkHitTester: Resolves a clickable LinkSpan under a control-relative mouse position. Generalizes the per-row link lookup so any markup-rendering control can hit-test links against a per-row list of spans (display-column coordinates).

Osc52: Builds OSC 52 clipboard escape sequences (and the tmux passthrough-wrapped form). Pure string logic — no I/O. The caller writes the returned sequence to the terminal.

PaletteColors: Color derivation helpers for palette-based theme generation: tint (toward white), shade (toward black), mix (toward another color), relative luminance, and a readable contrast color. All are reflection-free and built on BlendColor(Color, Color, float).

PanelBorderRenderer: Shared box-border drawing primitives used by panel-style controls. Extracted from PanelControl so both it and CollapsiblePanel can render identical bordered chrome without duplicating the drawing logic.

PathValidator: Centralised path validation for preventing path traversal, symlink following, and access to sensitive system directories. All file-access paths in the framework that accept external input should validate through this class.

ProcessRunner: Safe process execution helper that prevents command injection by always using ArgumentList (never string-concatenated arguments). All process spawning in the framework should go through this class.

PropertySetterHelper: Helper class for property setters with validation and invalidation. Eliminates 200-250 lines of duplicated Width/Height/Color property patterns across 14+ controls.

ScrollbarHelper: Shared scrollbar geometry, drawing, and hit testing logic. Used by ListControl, TreeControl, and TableControl.

ScrollingHelper: Helper class for managing viewport scrolling logic across scrollable controls. Consolidates duplicated scroll adjustment code from TreeControl, ListControl, and DropdownControl.

SelectionStateHelper: Helper class for managing selection state updates across controls. Eliminates code duplication and prevents double event firing bugs.

SequenceHelper: Provides helper methods and constants for handling ANSI escape sequences, mouse input parsing, and keyboard input processing in console applications.

SliderRenderingHelper: Shared rendering and math utilities for SliderControl and RangeSliderControl. Eliminates code duplication between the two slider implementations.

SpinnerTextAnimator: Drives an arbitrary text setter from a looping spinner frame cycle, using the window system's animation manager. Useful for animating a status-bar label or window title without a dedicated control. Dispose or Stop to end the animation.

StringBuilderExtensions: Extension methods for StringBuilder to support Rune (supplementary plane) characters.

TerminalCapabilities: Detects terminal rendering capabilities at runtime. Probed once during driver initialization; results are cached for the session.

TextMeasurementCache: Caches expensive text measurement operations for improved rendering performance. Eliminates duplicate measurements during rendering cycles (40+ calls per frame in complex controls). Thread-safe: uses ConcurrentDictionary to support concurrent read/write from render and UI threads.

TextSanitizer: Provides sanitization for text entering the character buffer. Prevents terminal escape injection by filtering control characters, BiDi overrides, and other unsafe runes before they reach cells.

TextTruncationHelper: Helper class for truncating text with ellipsis, handling Spectre.Console markup correctly. Consolidates 85% similar truncation logic from 4+ locations.

ThreadSafeStringBuilder: Provides a thread-safe wrapper around StringBuilder for concurrent string building operations.

UnicodeWidth: Provides display width information for Unicode characters. Delegates to the Wcwidth library for accurate width calculation including zero-width characters (combining marks, variation selectors, ZWJ). Spacing Combining Marks (Unicode category Mc) are corrected to width 1, as they occupy visual space in terminals despite Wcwidth marking them zero-width. Adapts to terminal capabilities: uses Unicode 15.0 width tables unless the terminal is detected to support Unicode 16.0 widths (probed at startup).

WordBoundaryHelper: Provides word boundary detection for text navigation and editing. Word characters: letters, digits, underscores. Everything else is a separator.

KeyCode: The KeyCode enumeration encodes key information from console drivers and provides a consistent way for application code to specify keys and receive key events.