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 (Simple API - Recommended)

use tui_dispatch::debug::DebugLayer;

// One line setup with sensible defaults:
let debug = DebugLayer::<MyAction>::simple();

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

// Default keybindings (when debug mode is active):
// - F12/Esc: Toggle debug mode
// - S: Show/hide state overlay
// - Y: Copy frozen frame to clipboard
// - I: Toggle mouse capture for cell inspection

Custom Configuration

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

// Use custom toggle key:
let debug = DebugLayer::<MyAction>::simple_with_toggle_key(&["F11"]);

// Or full control with custom context:
let config = DebugConfig::new(keybindings, MyContext::Debug);
let debug: DebugLayer<MyAction, MyContext> = DebugLayer::new(config);

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::default_debug_keybindings;

pub use config::default_debug_keybindings_with_toggle;

pub use config::DebugConfig;

pub use config::DebugStyle;

pub use config::KeyStyles;

pub use config::StatusItem;

pub use layer::DebugLayer;

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::ActionLog;

pub use action_logger::ActionLogConfig;

pub use action_logger::ActionLogEntry;

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::ActionLogDisplayEntry;

pub use table::ActionLogOverlay;

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::ActionLogStyle;

pub use widgets::ActionLogWidget;

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 and in-memory storage

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

Enums

SimpleDebugContext

Built-in context for simple debug layer usage.