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:
- Receives incoming
incin-telemetryEvents viaupdate(). - Renders itself to a bounded screen region using a
render_ctx::RenderCtxviarender(). - 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, mirroringincin-telemetry’serr.rsconvention. 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
Paneltrait 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-exportingratatui-widgetstypes directly).