Skip to main content

Crate incin_viz_plugin_api

Crate incin_viz_plugin_api 

Source
Expand description

incin-viz-plugin-api: The stable, independently-compilable trait surface for building custom visualizations and UI plugins for incin-viz.

This crate provides the foundational types and traits (Panel, Plugin, KeymapProvider, and RenderCtx) needed to extend the Incin Visualizer dashboard. By separating the plugin API from the main incin-viz crate, developers can build custom telemetry visualizers without pulling in heavy TUI or application runtime dependencies.

§Architecture

The plugin architecture revolves around the panel::Panel trait. A Panel is a stateful struct that:

  1. Receives incoming incin-telemetry Events via update().
  2. Renders itself to a bounded screen region using a render_ctx::RenderCtx via render().
  3. Responds to keyboard and mouse inputs via handle_event().

The render_ctx::RenderCtx provides a safe, abstracted interface to the underlying rendering engine (ratatui), preventing plugins from accidentally overwriting other panels or crashing the host application by drawing outside their assigned boundaries.

§Getting Started

To create a custom panel, implement the panel::Panel trait:

use incin_viz_plugin_api::prelude::*;
use incin_telemetry::events::{Event, ScalarEvent};

pub struct MyCustomPanel {
    current_value: f64,
}

impl Panel for MyCustomPanel {
    fn id(&self) -> &'static str { "my_custom_panel" }
    fn title(&self) -> &str { "Custom Metric" }
     
    fn update(&mut self, event: &Event) {
        if let Event::Scalar(ScalarEvent { value, .. }) = event {
            self.current_value = *value;
        }
    }
     
    fn render(&mut self, ctx: &mut RenderCtx<'_, '_>) {
        // Use ctx.buf() and ctx.area() to draw custom UI using ratatui
    }
     
    fn handle_event(&mut self, _event: &PanelEvent) -> bool { false }
    fn reset(&mut self) { self.current_value = 0.0; }
}

Once implemented, you can register it with incin-viz’s App at startup.

Modules§

err
Error types and result alias for plugin operations. Centralized error type for incin-viz-plugin-api, mirroring incin-telemetry’s err.rs convention. This crate has no JSON or socket I/O of its own, so its variant set is smaller.
event
Input events (keyboard, mouse, focus) for interactive panels. Thin newtypes over the crossterm event shape panels need, per UI-SPEC.md’s “incin-viz-plugin-api does not depend on crossterm” constraint.
keymap
Keymap actions and resolution. Keybinding resolution contract.
panel
State and lifecycle interface for visualizer panels. Contains the Panel trait which defines the core interface for UI plugins.
plugin
Plugin bundling interface. A plugin contributes one or more panels to the host.
prelude
Convenient re-exports for building visualizer plugins.
render_ctx
Rendering context wrapper for ratatui buffer access. Source: UI-SPEC.md’s locked render-context boundary (thin wrapper over ratatui::Frame/Rect, re-exporting ratatui-widgets types directly).