Skip to main content

Module debug

tui_dispatch

Module debug 

Source
Expand description

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
ⓘ
use tui_dispatch_debug::debug::DebugLayer;

// Minimal setup with sensible defaults (F12 toggle key)
let debug = DebugLayer::<MyAction>::simple().active(args.debug);

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

// Built-in keybindings (when debug mode is active):
// - Toggle key (e.g., F12): Toggle debug mode
// - S: Show/hide state overlay
// - B: Toggle debug banner position
// - /: Edit action-log search query
// - n/N: Next/previous action-log search match
// - J/K, arrows, PgUp/PgDn, g/G: Scroll overlays
// - Y: Copy frozen frame to clipboard
// - W: Save state snapshot as JSON
// - I: Toggle mouse capture for cell inspection

§Customization

ⓘ
use crossterm::event::KeyCode;
use tui_dispatch_debug::debug::{BannerPosition, DebugLayer, DebugStyle};

let debug = DebugLayer::<MyAction>::new(KeyCode::F(11))
    .with_banner_position(BannerPosition::Top)
    .with_action_log_capacity(500)
    .with_style(DebugStyle::default())
    .active(args.debug);

§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_debug::debug::ActionLoggerConfig;

// Log only Search* and Connect* actions
let config = ActionLoggerConfig::new(Some("Search*,Connect*"), None);
// Prefix filters: cat:<category>, name:<ExactActionName>
let config = ActionLoggerConfig::new(Some("cat:search,name:SearchSubmit"), 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
format
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 include/exclude 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.
DebugOutcome
Result of handling a debug event.
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
ScrollbarStyle
Style and symbol overrides for debug scrollbars
StatusItem
Status item for the debug banner

Enums§

BannerPosition
Location of the debug banner relative to the app area.
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 default debug keybindings.

Traits§

DebugState
Trait for types that can provide debug state information

Functions§

buffer_to_text
Convert a buffer to plain text (for clipboard export)
debug_string
debug_string_compact
debug_string_pretty
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