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);
}

Re-exports

pub use actions::DebugAction;

pub use actions::DebugSideEffect;

pub use config::DebugConfig;

pub use config::DebugStyle;

pub use config::StatusItem;

pub use layer::DebugLayer;

pub use layer::DebugLayerBuilder;

pub use state::DebugEntry;

pub use state::DebugSection;

pub use state::DebugState;

pub use state::DebugWrapper;

pub use action_logger::glob_match;

pub use action_logger::ActionLoggerConfig;

pub use action_logger::ActionLoggerMiddleware;

pub use cell::format_color_compact;

pub use cell::format_modifier_compact;

pub use cell::inspect_cell;

pub use cell::point_in_rect;

pub use cell::CellPreview;

pub use table::DebugOverlay;

pub use table::DebugTableBuilder;

pub use table::DebugTableOverlay;

pub use table::DebugTableRow;

pub use widgets::buffer_to_text;

pub use widgets::dim_buffer;

pub use widgets::paint_snapshot;

pub use widgets::BannerItem;

pub use widgets::CellPreviewWidget;

pub use widgets::DebugBanner;

pub use widgets::DebugTableStyle;

pub use widgets::DebugTableWidget;

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

DebugFreeze

Debug freeze state for capturing and inspecting UI frames