Raibid Labs Documentation

PLUGIN_INSPECTOR_SUMMARY

7 min read

Plugin Inspector Implementation Summary

Overview

Successfully designed and implemented a comprehensive visual plugin debugger/inspector UI for the Scarab terminal emulator client. The inspector provides plugin developers with real-time visibility into plugin behavior, performance metrics, error tracking, and control capabilities.

Deliverables

1. Core Implementation

File: /home/beengud/raibid-labs/scarab/crates/scarab-client/src/plugin_inspector.rs (850 lines)

A complete Bevy plugin with:

  • PluginInspectorState resource tracking UI state, plugins, logs, and hook history
  • InspectedPlugin data structure with runtime metrics
  • LogEntry and HookExecution tracking structures
  • Five inspection tabs: Overview, Metadata, Hooks, Logs, Source
  • Real-time updates via IPC message handling
  • Filtering and search for plugins and logs
  • Export functionality for debug information

2. Protocol Extensions

File: /home/beengud/raibid-labs/scarab/crates/scarab-protocol/src/lib.rs (Updated)

New message types for plugin inspection:

Control Messages (Client → Daemon):

PluginListRequest,
PluginEnable { name: String },
PluginDisable { name: String },
PluginReload { name: String },

Daemon Messages (Daemon → Client):

PluginList { plugins: Vec<PluginInspectorInfo> },
PluginStatusChanged { name: String, enabled: bool },
PluginError { name: String, error: String },

New Type:

pub struct PluginInspectorInfo {
    pub name: String,
    pub version: String,
    pub description: String,
    pub author: String,
    pub homepage: Option<String>,
    pub api_version: String,
    pub min_scarab_version: String,
    pub enabled: bool,
    pub failure_count: u32,
}

3. Feature Flag Integration

File: /home/beengud/raibid-labs/scarab/crates/scarab-client/Cargo.toml (Updated)

Added plugin-inspector feature flag:

[dependencies]
bevy_egui = { version = "0.31", optional = true }
 
[features]
plugin-inspector = ["bevy_egui"]

Conditional compilation in:

  • src/lib.rs: Module and exports
  • src/main.rs: Plugin registration

4. Documentation

User Documentation: /home/beengud/raibid-labs/scarab/crates/scarab-client/PLUGIN_INSPECTOR.md

  • Complete feature overview
  • Usage instructions with screenshots (text-based)
  • Build instructions
  • Troubleshooting guide
  • Architecture explanation
  • Future enhancements roadmap

Design Documentation: /home/beengud/raibid-labs/scarab/docs/plugin-inspector-ui-design.md

  • ASCII mockups of all UI screens
  • Component breakdown
  • Color palette specification
  • Typography guidelines
  • Spacing and layout rules
  • Interaction states
  • Accessibility considerations
  • Responsive behavior
  • Implementation notes

Features Implemented

Plugin List View

  • Color-coded status indicators (green/red/gray)
  • Live filtering by name, description, or author
  • Version display and failure count badges
  • Scrollable list with selection state
  • Real-time updates from daemon

Overview Tab

  • Status dashboard with enable/disable state
  • Performance metrics:
    • Total hook executions
    • Total execution time
    • Average execution time per hook
  • Failure count tracking
  • Last error message display (when present)
  • Enable/Disable/Reload action buttons

Metadata Tab

  • Complete plugin information display
  • Grid layout with labeled fields:
    • Name, version, description
    • Author and clickable homepage link
    • API version and minimum Scarab version
  • Striped rows for readability

Hooks Tab

  • Execution history (last 100 hooks)
  • Statistics summary:
    • Total executions
    • Success vs failed count
    • Average execution time
  • Detailed hook records:
    • Timestamp (relative time)
    • Hook type (on_output, on_input, etc.)
    • Execution duration
    • Error messages for failures
  • Color-coded success/failure indicators

Logs Tab

  • Real-time log streaming with auto-scroll option
  • Log level filtering (Trace, Debug, Info, Warn, Error)
  • Plugin attribution for each log entry
  • Search/filter functionality
  • Color-coded log levels with icons
  • Relative timestamps
  • Clear button for log management

Source Tab

  • Placeholder UI for future features
  • Documentation of planned capabilities:
    • Source code viewing (.fsx files)
    • Bytecode inspection (.fzb files)
    • Configuration display
    • Dependency tree visualization

System Integration

  • Keybinding: Ctrl+Shift+P to toggle inspector
  • IPC Integration: Seamless communication with daemon
  • Message Handling: Processes PluginList, PluginStatusChanged, PluginError
  • Export Function: Saves debug info to timestamped file
  • Memory Management: Circular buffers with configurable limits (1000 logs, 500 hooks)

UI Design Principles

Visual Design

  • Dark theme optimized for long coding sessions
  • Semantic color coding: Green (success), Red (error), Yellow (warning), Blue (info)
  • Three-panel layout: Sidebar (plugins) + Toolbar (actions) + Content (details)
  • Responsive: Resizable panels, scrollable content

Interaction Design

  • Instant feedback on all actions
  • Visual affordances: Hover states, selection highlighting
  • Keyboard accessible: Tab navigation, Enter to activate
  • Error-tolerant: Graceful handling of missing data

Performance

  • Conditional rendering: Only draws when visible
  • Efficient updates: Only re-renders on state changes
  • Bounded memory: Automatic pruning of old logs/history
  • Smooth scrolling: 60fps target

Technical Architecture

Client-Side (Bevy)

PluginInspectorPlugin
├── Resources
│   └── PluginInspectorState
├── Systems
│   ├── toggle_inspector_input (keyboard)
│   ├── render_inspector_ui (egui)
│   └── handle_plugin_messages (IPC)
└── Dependencies
    ├── bevy_egui (UI rendering)
    ├── IpcChannel (communication)
    └── RemoteMessageEvent (event handling)

Data Flow

User Input (Ctrl+Shift+P)
    ↓
toggle_inspector_input system
    ↓
State.visible = true
    ↓
Send PluginListRequest via IPC
    ↓
Daemon responds with PluginList
    ↓
handle_plugin_messages system
    ↓
State.update_plugins()
    ↓
render_inspector_ui draws UI
    ↓
User clicks Enable/Disable
    ↓
Send PluginEnable/Disable via IPC
    ↓
Daemon responds with PluginStatusChanged
    ↓
State updates plugin status
    ↓
UI automatically reflects changes

Protocol Design

  • Zero-copy serialization via rkyv
  • Incremental updates: Only changed data sent
  • Request-response pattern: Client requests, daemon responds
  • Push notifications: Daemon pushes status changes
  • Efficient wire format: Minimal bandwidth usage

Build Instructions

cargo build -p scarab-client --features plugin-inspector
cargo run -p scarab-client --features plugin-inspector

Disable Inspector (Smaller Binary)

cargo build -p scarab-client

Usage Instructions

  1. Start daemon (if not running):

    cargo run -p scarab-daemon

  2. Start client with inspector:

    cargo run -p scarab-client --features plugin-inspector

  3. Open inspector: Press Ctrl+Shift+P

  4. Browse plugins: Click on any plugin in the sidebar

  5. View details: Switch between tabs (Overview, Metadata, Hooks, Logs, Source)

  6. Manage plugins:

    • Click “Enable” or “Disable” to toggle
    • Click “Reload” to restart a plugin
    • Click “Refresh” to update plugin list

  7. Monitor activity: Watch the Logs tab for real-time output

  8. Debug issues:

    • Check failure count in sidebar
    • View last error in Overview tab
    • Review hook history in Hooks tab
    • Export debug info for sharing

Files Created/Modified

New Files

  1. /home/beengud/raibid-labs/scarab/crates/scarab-client/src/plugin_inspector.rs - Main implementation
  2. /home/beengud/raibid-labs/scarab/crates/scarab-client/PLUGIN_INSPECTOR.md - User documentation
  3. /home/beengud/raibid-labs/scarab/docs/plugin-inspector-ui-design.md - Design specification
  4. /home/beengud/raibid-labs/scarab/PLUGIN_INSPECTOR_SUMMARY.md - This file

Modified Files

  1. /home/beengud/raibid-labs/scarab/crates/scarab-client/Cargo.toml - Added bevy_egui dependency and feature flag
  2. /home/beengud/raibid-labs/scarab/crates/scarab-client/src/lib.rs - Added module export with feature gate
  3. /home/beengud/raibid-labs/scarab/crates/scarab-client/src/main.rs - Conditional plugin registration
  4. /home/beengud/raibid-labs/scarab/crates/scarab-protocol/src/lib.rs - Added plugin inspection messages

Testing Checklist

Basic functionality (implementable now):

  • Inspector opens with Ctrl+Shift+P
  • Inspector closes when X clicked
  • All five tabs are accessible
  • Plugin list displays (may be empty without daemon support)
  • Filter box filters plugins by name
  • Log tab shows inspector open message
  • Export creates file in current directory
  • Window is resizable
  • Sidebar is resizable

Full functionality (requires daemon implementation):

  • Plugin list populates from daemon
  • Enable/Disable buttons work
  • Reload button works
  • Status changes reflect in UI
  • Performance metrics update
  • Hook history populates
  • Logs stream from plugins
  • Error messages display correctly

Future Work (Not Implemented)

Daemon-Side Handler

The client is complete, but the daemon needs:

  1. Handler for PluginListRequest in IPC server
  2. Handler for PluginEnable/Disable/Reload
  3. Broadcasting of PluginStatusChanged events
  4. Error notification via PluginError messages

Example daemon handler (for reference):

// In scarab-daemon/src/ipc/mod.rs or similar
async fn handle_control_message(
    msg: ControlMessage,
    plugin_manager: &mut PluginManager,
    client_id: u64,
) -> Result<()> {
    match msg {
        ControlMessage::PluginListRequest => {
            let plugins = plugin_manager.list_plugins()
                .into_iter()
                .map(|p| PluginInspectorInfo {
                    name: p.name,
                    version: p.version,
                    // ... map fields
                })
                .collect();
 
            send_to_client(client_id, DaemonMessage::PluginList { plugins }).await?;
        }
        ControlMessage::PluginEnable { name } => {
            plugin_manager.enable_plugin(&name)?;
            broadcast(DaemonMessage::PluginStatusChanged {
                name,
                enabled: true
            }).await?;
        }
        // ... handle other messages
    }
    Ok(())
}

Advanced Features

Not in scope for this implementation:

  • Source code viewer with syntax highlighting
  • Bytecode disassembler
  • Visual timeline/flamegraph for hook execution
  • Memory usage tracking
  • Interactive debugging (breakpoints, step-through)
  • Plugin configuration editor
  • Plugin marketplace integration

Benefits

For Plugin Developers

  • Rapid debugging: See errors immediately without grepping logs
  • Performance insight: Identify slow hooks causing latency
  • State visibility: Understand plugin lifecycle and behavior
  • Quick iteration: Enable/disable/reload without restarting Scarab

For Scarab Users

  • Transparency: See what plugins are doing
  • Troubleshooting: Identify misbehaving plugins
  • Control: Enable/disable plugins dynamically
  • Confidence: Monitor plugin health at a glance

For Scarab Development

  • Testing: Visual feedback during plugin system development
  • Debugging: Helps debug the plugin infrastructure itself
  • Documentation: Living example of IPC and remote UI patterns
  • Extensibility: Template for other inspector/debugger tools

Conclusion

The Plugin Inspector provides a professional-grade debugging interface for the Scarab plugin system. It leverages modern UI patterns (egui), efficient protocols (rkyv), and thoughtful design to create a tool that’s both powerful for developers and accessible for users.

The implementation is feature-complete on the client side, fully documented, and ready for integration once the daemon-side handlers are implemented. The modular architecture ensures easy maintenance and extension as the plugin system evolves.

Next Steps

To fully enable the inspector:

  1. Implement daemon handlers for plugin inspection messages
  2. Test end-to-end with real plugins
  3. Gather feedback from plugin developers
  4. Iterate on UX based on real-world usage
  5. Add advanced features (source viewer, flamegraph, etc.)

Screenshots/Mockups

Full ASCII mockups and design specifications are available in:

  • /home/beengud/raibid-labs/scarab/docs/plugin-inspector-ui-design.md

The UI design follows modern IDE patterns with:

  • Dark theme optimized for developers
  • Information density without clutter
  • Intuitive navigation via tabs and sidebar
  • Real-time updates without manual refreshes
  • Professional appearance matching terminal aesthetic

Graph View