Module debug 

Debug and inspection utilities for TUI applications

This module provides tools for debugging TUI applications:

• DebugLayer: High-level wrapper with automatic rendering (recommended)
• Action Logging: Pattern-based filtering for action logs
• Frame Freeze: Capture and inspect UI state
• Cell Inspection: Examine individual buffer cells
• Debug Widgets: Render debug overlays and tables

Quick Start (DebugLayer - Recommended)

use tui_dispatch::debug::{DebugLayer, DebugConfig, DebugAction};

// In your app:
let config = DebugConfig::new(keybindings, MyContext::Debug);
let debug: DebugLayer<MyAction, MyContext> = DebugLayer::new(config);

// In render loop - automatic handling:
debug.render(frame, |f, area| {
    render_main_ui(f, area, &state);
});

// In event loop:
if let Some(debug_action) = DebugAction::from_command(&cmd) {
    if let Some(side_effect) = debug.handle_action(debug_action) {
        // Handle clipboard, mouse capture, etc.
    }
}

Manual Control (Escape Hatch)

// Split area manually
let (app_area, banner_area) = debug.split_area(frame.area());

// Custom layout
render_my_ui(frame, app_area);

// Let debug layer render its parts
debug.render_overlay(frame, app_area);
debug.render_banner(frame, banner_area);

State Inspection

Implement DebugState for your state types:

use tui_dispatch::debug::{DebugState, DebugSection};

impl DebugState for AppState {
    fn debug_sections(&self) -> Vec<DebugSection> {
        vec![
            DebugSection::new("Connection")
                .entry("host", &self.host)
                .entry("status", format!("{:?}", self.status)),
        ]
    }
}

// Then show it:
debug.show_state_overlay(&app_state);

Action Logging

Use ActionLoggerMiddleware for pattern-based action filtering:

use tui_dispatch_core::debug::ActionLoggerConfig;

// Log only Search* and Connect* actions
let config = ActionLoggerConfig::new(Some("Search*,Connect*"), None);

// Log everything except Tick and Render (default excludes)
let config = ActionLoggerConfig::default();

Low-Level API

For full control, use DebugFreeze directly:

use tui_dispatch::debug::{DebugFreeze, paint_snapshot, dim_buffer};

let debug: DebugFreeze<MyAction> = DebugFreeze::default();

// In render loop:
if debug.enabled {
    if debug.pending_capture || debug.snapshot.is_none() {
        render_app(f, state);
        debug.capture(f.buffer());
    } else {
        paint_snapshot(f, debug.snapshot.as_ref().unwrap());
    }
    dim_buffer(f.buffer_mut(), 0.7);
    render_debug_overlay(f, &debug);
}

Modules

action_logger

Action logging with pattern-based filtering

actions

Debug actions and side effects

cell

Cell inspection utilities

config

Debug layer configuration

layer

High-level debug layer for TUI applications

state

Debug state introspection trait

table

Debug table types and builder

widgets

Debug rendering utilities and widgets

Structs

ActionLoggerConfig

Configuration for action logging with glob pattern filtering.

ActionLoggerMiddleware

Middleware that logs actions with configurable pattern filtering.

BannerItem

An item in a debug banner (status bar)

CellPreview

Visual representation of a buffer cell for debug preview

CellPreviewWidget

A widget that renders a cell preview

DebugBanner

A debug banner widget (status bar at bottom)

DebugConfig

Configuration for the debug layer

DebugEntry

A debug entry (key-value pair)

DebugFreeze

Debug freeze state for capturing and inspecting UI frames

DebugLayer

High-level debug layer with sensible defaults

DebugLayerBuilder

Builder for DebugLayer with ergonomic configuration

DebugSection

A debug section with a title and entries

DebugStyle

Style configuration for debug UI

DebugTableBuilder

Builder for constructing debug tables

DebugTableOverlay

A debug table overlay with title, rows, and optional cell preview

DebugTableStyle

Style configuration for debug table rendering

DebugTableWidget

A debug table widget that renders a DebugTableOverlay

DebugWrapper

Wrapper to use Debug impl as DebugState

StatusItem

Status item for the debug banner

Enums

DebugAction

Debug actions provided by tui-dispatch

DebugOverlay

Type of debug overlay

DebugSideEffect

Side effects that the app needs to handle after debug actions

DebugTableRow

A row in a debug table - either a section header or a key-value entry

Traits

DebugState

Trait for types that can provide debug state information

Functions

buffer_to_text

Convert a buffer to plain text (for clipboard export)

dim_buffer

Dim a buffer by blending with a darker shade

format_color_compact

Format a color as a compact string for display

format_modifier_compact

Format modifiers as a compact string

glob_match

Simple glob pattern matching supporting * and ?.

inspect_cell

Inspect a cell at the given position in a buffer

paint_snapshot

Paint a snapshot buffer onto the current frame

point_in_rect

Check if a point is within a rectangle