Struct HostBindings 

pub struct HostBindings {
    pub limits: HostBindingLimits,
    pub capabilities: PluginNavCapabilities,
    /* private fields */
}

ECS-safe host bindings for Fusabi plugins

This struct provides the bridge between Fusabi scripts and Scarab’s ECS. All operations are validated against capability flags, quotas, and rate limits before being queued as RemoteCommands for the plugin host to process.

Thread Safety

All methods are thread-safe and can be called from async Fusabi contexts.

Example

let bindings = HostBindings::new(limits, capabilities);

// Register a focusable (checks quotas and validates)
bindings.register_focusable(&ctx, PluginFocusable {
    x: 10, y: 5, width: 20, height: 1,
    label: "GitHub".into(),
    action: PluginFocusableAction::OpenUrl("https://github.com".into()),
})?;

// Enter hint mode (checks capability and rate limit)
bindings.enter_hint_mode(&ctx)?;

Fields

limits: HostBindingLimits

Configuration limits

capabilities: PluginNavCapabilities

Navigation capabilities

Implementations

impl HostBindings

pub fn new( limits: HostBindingLimits, capabilities: PluginNavCapabilities, ) -> Self

Create new host bindings with the specified limits and capabilities

pub fn with_defaults() -> Self

Create with default limits and capabilities

pub fn enter_hint_mode(&self, ctx: &PluginContext) -> Result<()>

Enter hint mode

Triggers the navigation hint mode UI, displaying labels for all focusable elements.

Errors

Returns error if:

• Plugin doesn’t have can_enter_hint_mode capability
• Rate limit exceeded

pub fn exit_nav_mode(&self, ctx: &PluginContext) -> Result<()>

Exit navigation mode

Exits hint mode and returns to normal input handling.

Errors

Returns error if rate limit exceeded

pub fn register_focusable( &self, ctx: &PluginContext, region: PluginFocusable, ) -> Result<u64>

Register a focusable region

Registers a custom navigation target that will appear in hint mode. The region is validated for bounds and the action is checked for safety.

Arguments

• ctx - Plugin context
• region - Focusable region to register

Returns

Unique ID for this focusable (can be used to unregister)

Errors

Returns error if:

• Plugin doesn’t have can_register_focusables capability
• Plugin has reached max_focusables quota
• Region fails validation (coordinates, dimensions, URL safety)
• Rate limit exceeded

pub fn unregister_focusable( &self, ctx: &PluginContext, focusable_id: u64, ) -> Result<()>

Unregister a focusable region

Removes a previously registered focusable from the navigation system.

Arguments

• ctx - Plugin context
• focusable_id - ID returned from register_focusable

Errors

Returns error if rate limit exceeded

pub fn set_nav_style(&self, style: NavStyle)

Set navigation style

Configures the visual style of navigation hints (character set, appearance).

pub fn nav_style(&self) -> NavStyle

Get current navigation style

pub fn set_nav_keymap(&self, keymap: NavKeymap)

Set navigation keymap

Configures the keybindings for navigation mode.

pub fn nav_keymap(&self) -> NavKeymap

Get current navigation keymap

pub fn resource_usage(&self) -> ResourceUsage

Get current resource usage

pub fn reset_rate_limit(&self)

Reset rate limiter (useful for testing)

pub fn spawn_overlay( &self, ctx: &PluginContext, config: OverlayConfig, ) -> Result<u64>

Spawn an overlay at the given position

Creates a floating overlay element at the specified terminal coordinates. Overlays are useful for tooltips, popups, and other transient UI elements.

Arguments

• ctx - Plugin context
• config - Overlay configuration (position, content, style)

Returns

Unique ID for this overlay (can be used to remove it later)

Errors

Returns error if:

• Plugin has reached max_overlays quota
• Rate limit exceeded
• Overlay position is out of bounds

pub fn remove_overlay(&self, ctx: &PluginContext, overlay_id: u64) -> Result<()>

Remove a previously spawned overlay

Removes an overlay by its ID. If the overlay doesn’t exist, this is a no-op.

Arguments

• ctx - Plugin context
• overlay_id - ID returned from spawn_overlay

Errors

Returns error if rate limit exceeded

pub fn add_status_item( &self, ctx: &PluginContext, item: StatusBarItem, ) -> Result<u64>

Add a status bar item

Adds an item to the terminal status bar. Status items are positioned based on their priority (higher priority = further right).

Arguments

• ctx - Plugin context
• item - Status bar item configuration

Returns

Unique ID for this status item (can be used to remove it later)

Errors

Returns error if:

• Plugin has reached max_status_items quota
• Rate limit exceeded

pub fn remove_status_item( &self, ctx: &PluginContext, item_id: u64, ) -> Result<()>

Remove a status bar item

Removes a status bar item by its ID. If the item doesn’t exist, this is a no-op.

Arguments

• ctx - Plugin context
• item_id - ID returned from add_status_item

Errors

Returns error if rate limit exceeded

pub fn prompt_jump( &self, ctx: &PluginContext, direction: JumpDirection, ) -> Result<()>

Trigger prompt jump navigation

Navigates the terminal viewport to the previous/next command prompt in the scrollback buffer. Useful for quickly navigating command history.

Arguments

• ctx - Plugin context
• direction - Direction to jump (Up, Down, First, Last)

Errors

Returns error if rate limit exceeded

pub fn apply_theme(&self, ctx: &PluginContext, theme_name: &str) -> Result<()>

Apply a named theme

Dynamically applies a color theme to the terminal. The theme must be one of the built-in themes or a custom theme registered with the configuration system.

Built-in Themes

• slime - Vibrant green tones (default)
• dracula - Dark purple theme
• nord - Arctic, north-bluish color palette
• monokai - Classic dark theme with warm accents
• gruvbox_dark - Retro groove color scheme
• solarized_dark - Precision colors for machines
• solarized_light - Light variant of solarized
• tokyo_night - A clean, dark theme from Tokyo
• catppuccin - Soothing pastel theme

Arguments

• ctx - Plugin context
• theme_name - Name of the theme to apply

Errors

Returns error if rate limit exceeded

Example

Host.applyTheme ctx "dracula"

pub fn set_palette_color( &self, ctx: &PluginContext, color_name: &str, value: &str, ) -> Result<()>

Set a specific palette color

Modifies a single color in the current palette. This allows fine-grained customization of terminal colors without changing the entire theme.

Color Names

• foreground, background
• black, red, green, yellow, blue, magenta, cyan, white
• bright_black, bright_red, bright_green, bright_yellow
• bright_blue, bright_magenta, bright_cyan, bright_white
• cursor, selection

Color Values

Colors can be specified as:

• Hex: #RRGGBB or RRGGBB
• RGB: rgb(255, 0, 128)
• Named: red, green, blue, etc.

Arguments

• ctx - Plugin context
• color_name - Name of the color to set
• value - New color value (hex, rgb, or named)

Errors

Returns error if rate limit exceeded

Example

Host.setPaletteColor ctx "foreground" "#00FF00"
Host.setPaletteColor ctx "background" "rgb(30, 30, 30)"

pub fn get_current_theme(&self, ctx: &PluginContext) -> Result<()>

Request the current theme name

Queries the current active theme name. Since this is an async operation, the result will be delivered via a callback or event.

Arguments

• ctx - Plugin context

Errors

Returns error if rate limit exceeded

Note

The theme name is returned asynchronously. Plugins should listen for the ThemeInfoResponse event to receive the result.

Trait Implementations

impl Debug for HostBindings

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.