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

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

ActionLog

In-memory ring buffer for storing recent actions

ActionLogConfig

Configuration for the action log ring buffer

ActionLogDisplayEntry

A display-ready action log entry

ActionLogEntry

An entry in the action log

ActionLogOverlay

Overlay for displaying the action log

ActionLogStyle

Style configuration for action log rendering

ActionLogWidget

A widget for rendering an action log overlay

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 minimal 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

KeyStyles

Styles for different debug key hints

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

SimpleDebugContext

Built-in context for simple debug layer usage.

Traits

DebugState

Trait for types that can provide debug state information

Functions

buffer_to_text

Convert a buffer to plain text (for clipboard export)

default_debug_keybindings

Create default debug keybindings with F12/Esc to toggle.

default_debug_keybindings_with_toggle

Create debug keybindings with custom toggle key(s).

dim_buffer

Dim a buffer by scaling colors towards black

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