Index of every page on this site: llms.txt
All skills
  • 1 file
  • 16.1 KB
  • Updated 9 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/alpha-innovation-labs/opencode-rs-sdk/ratkit

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈2 tokens for metadata: the name and description. ≈4.1k when used: this file.

SKILL.md has missing or invalid fields
  • The name in the SKILL.md header is missing or is not text.
  • The description in the SKILL.md header is missing or is not text.
Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

ratkit

Comprehensive Rust TUI component library built on ratatui 0.29, providing 21 feature-gated modules (primitives, widgets, services) for building rich terminal applications.

This file provides a complete reference for working with the ratkit codebase. The repository is organized as a single crate at the root level with feature-based modularity. Use this guide to understand component relationships, find APIs, and follow established patterns when implementing new features.

Agent Operating Rules

  1. Single crate at root: All code is in src/ with 21 feature flags (e.g., button, pane, markdown-preview)
  2. Enable features explicitly: No default features; add required features to Cargo.toml (e.g., features = ["button", "dialog"])
  3. Cross-feature dependencies: Some features auto-enable others (e.g., tree-view enables widget-event, repo-watcher enables file-watcher and git-watcher)
  4. Use just for all operations: Build (just build), test (just test), check (just check), demos (just demo)
  5. Run examples with --features flag: Examples require their specific features (e.g., --features markdown-preview)
  6. Import from crate root: All public APIs are re-exported from ratkit:: (e.g., use ratkit::Button)
  7. StatefulWidget pattern: Complex widgets require separate state structs persisted in app state
  8. Event loop polling: Services require regular check_for_changes() calls in the event loop
  9. Mouse capture required: Enable crossterm mouse capture for interactive widgets
  10. Persist widget state: Never create widget state in render loops - store in app struct
  11. Validate before commits: Run just check (format + lint + test) before committing
  12. Verify feature flags: Compilation errors often indicate missing feature flags in Cargo.toml

Environment and Version Constraints

  • Rust 1.70+ required (workspace.rust-version in Cargo.toml)
  • ratatui 0.29 as the underlying rendering library
  • crossterm 0.28 for terminal input/events
  • tokio for async runtime
  • Single crate at root with 21 feature flags (no workspace members)
  • 23 examples in examples/ (moved from crates/ratkit/examples/)
  • Optional external deps: notify (file watching), reqwest (ai-chat), pulldown-cmark/syntect (markdown), similar (code-diff)

Quick Task Playbooks

Run an example

  • Where to edit: N/A
  • Related files: examples/
  • Validation: cargo run --example button_button_demo --features button

Run with just

  • Where to edit: N/A
  • Related files: justfile
  • Validation: just demo (interactive picker) or just demo-md, just demo-term, etc.

Build with specific features

  • Where to edit: Cargo.toml (root level)
  • Related files: Feature definitions
  • Validation: cargo build --features "button,pane,dialog"

Build all features

  • Where to edit: N/A
  • Related files: All source files
  • Validation: cargo build --all-features

Run full verification

  • Where to edit: N/A
  • Related files: All source files
  • Validation: just check (runs fmt-check, lint, test)

Getting Started

# Cargo.toml - enable specific features
[dependencies]
ratkit = { version = "0.2", features = ["button", "dialog", "pane"] }
use ratkit::prelude::*;
use ratatui::Frame;

struct MyApp;

impl CoordinatorApp for MyApp {
    fn on_event(&mut self, event: CoordinatorEvent) -> LayoutResult<CoordinatorAction> {
        match event {
            CoordinatorEvent::Keyboard(keyboard) => {
                if keyboard.is_escape() {
                    return Ok(CoordinatorAction::Quit);
                }
            }
            _ => {}
        }
        Ok(CoordinatorAction::Continue)
    }

    fn on_draw(&mut self, frame: &mut Frame) {
        // Render your UI here
    }
}

fn main() -> std::io::Result<()> {
    let app = MyApp;
    run(app, RunnerConfig::default())
}

Workspace Overview

The ratkit workspace contains a single crate with 21 feature-gated modules organized into:

  • Primitives (11 modules): Core UI building blocks in src/primitives/
    • button, pane, dialog, toast, statusline, scroll, menu_bar, resizable_grid, tree_view, widget_event, termtui
  • Widgets (6 modules): Higher-level composite widgets in src/widgets/
    • markdown_preview, code_diff, ai_chat, hotkey_footer, file_system_tree, theme_picker
  • Services (4 modules): Background monitoring services in src/services/
    • file_watcher, git_watcher, repo_watcher, hotkey_service
  • Core Runtime (1 module): Application lifecycle in src/core/

All modules follow feature-gated compilation. Enable only what you need.

Core Runtime

The core runtime provides the application lifecycle, event routing, and element management for terminal UI applications.

Key Components

  • CoordinatorApp trait: Applications implement this to receive events and render
  • run() / run_with_diagnostics(): Entry points to start the event loop
  • Element trait: Implement for custom widgets that integrate with the coordinator
  • RunnerConfig: Configuration for tick rate, layout debounce, mouse capture

Architecture

  • Three-region layout: Top, Center, Bottom
  • Focus management with stack and traversal
  • Mouse routing with z-order hit testing
  • Element registry with weak references

UI Primitives

Core UI building blocks for TUI applications, located in src/primitives/.

Feature Flags

Each primitive has an individual feature flag:

  • button, pane, dialog, toast, statusline, scroll
  • menu-bar (enables widget-event)
  • resizable-grid
  • tree-view (enables widget-event)
  • widget-event
  • termtui

Common Patterns

  • Builder pattern with new() and with_* methods
  • StatefulWidget pattern for complex state
  • Event emission via WidgetEvent
  • Mouse/keyboard interaction support

Complex Widgets

Higher-level composite widgets in src/widgets/.

Feature Flags

  • markdown-preview - Most complex (syntax highlighting, TOC, themes, selection)
  • code-diff - VS Code-style diff viewer
  • ai-chat - AI chat interface (requires reqwest, serde)
  • hotkey-footer - Keyboard shortcut footer
  • file-system-tree - File browser with devicons
  • theme-picker - Theme selector with 25+ themes

External Dependencies

Widget Dependencies
ai-chat reqwest, serde, serde_json
markdown-preview pulldown-cmark, syntect, syntect-tui, notify, arboard, dirs
code-diff similar
file-system-tree devicons

Services

Background monitoring services in src/services/.

Feature Flags

  • file-watcher - Watch files/directories for changes
  • git-watcher - Monitor git repository state
  • repo-watcher - Combined file + git watching (enables file-watcher and git-watcher)
  • hotkey-service - Global hotkey registration and management

Common Dependencies

All watcher services use the notify crate for filesystem events.

Usage Cards

CoordinatorApp

  • Use when: Building any ratkit TUI application
  • Enable/Install: Core runtime, no feature flag needed
  • Import/Invoke: use ratkit::prelude::*;
  • Minimal flow:
    1. Define struct implementing CoordinatorApp
    2. Implement on_event() to handle events
    3. Implement on_draw() to render UI
    4. Call run(app, RunnerConfig::default())
  • Key APIs: on_event(), on_draw(), on_layout_changed()
  • Pitfalls: Runner takes ownership; wrap shared state in Arc<RwLock<>>
  • Source: src/coordinator.rs, src/runner_helper.rs

run()

  • Use when: Starting the main application event loop
  • Enable/Install: Core runtime, no feature flag
  • Import/Invoke: use ratkit::{run, run_with_diagnostics};
  • Minimal flow:
    1. Create app implementing CoordinatorApp
    2. Create RunnerConfig::default() or custom
    3. Call run(app, config) or run_with_diagnostics(app, config) for debug overlay
  • Key APIs: run(), run_with_diagnostics(), RunnerConfig
  • Pitfalls: Blocks until exit; handles terminal init/cleanup
  • Source: src/runner_helper.rs

Element

  • Use when: Creating custom widgets that integrate with coordinator
  • Enable/Install: Core runtime
  • Import/Invoke: use ratkit::Element;
  • Minimal flow:
    1. Implement Element trait for your widget
    2. Define id(), on_render(), on_keyboard(), on_mouse()
    3. Register with ElementMetadata and region
  • Key APIs: id(), on_render(), on_keyboard(), on_mouse(), on_focus_gain(), on_focus_loss(), on_tick()
  • Pitfalls: Registry stores weak refs - keep strong refs in app state; return true when handling events
  • Source: src/registry.rs

Button

  • Use when: Clickable button with hover states
  • Enable/Install: features = ["button"]
  • Import/Invoke: use ratkit::Button;
  • Minimal flow:
    1. Create Button::new("Label")
    2. Call update_hover(x, y) on mouse move
    3. Call is_clicked(x, y) on click
    4. Render with render_with_title()
  • Key APIs: new(), normal_style(), hover_style(), update_hover(), is_clicked()
  • Pitfalls: State must persist in app struct
  • Source: src/primitives/button/widget.rs

Pane

  • Use when: Styled panel container with title/icon/padding
  • Enable/Install: features = ["pane"]
  • Import/Invoke: use ratkit::Pane;
  • Minimal flow:
    1. Create Pane::new("Title")
    2. Chain builder methods: with_icon(), with_padding(), border_style()
    3. Render as widget
  • Key APIs: new(), with_icon(), with_padding(), with_uniform_padding(), border_style()
  • Pitfalls: Padding reduces inner content area
  • Source: src/primitives/pane/mod.rs

Dialog

  • Use when: Modal dialogs for confirmation/information
  • Enable/Install: features = ["dialog"]
  • Import/Invoke: use ratkit::{Dialog, DialogState, DialogType};
  • Minimal flow:
    1. Create Dialog::new(title, message) or use builder (Dialog::confirm())
    2. Set buttons with .buttons(vec!["Yes", "No"])
    3. Create DialogState::new() for button selection
    4. Render with DialogWidget
  • Key APIs: new(), info(), warning(), error(), success(), confirm(), buttons()
  • Pitfalls: DialogState must persist; uses StatefulWidget pattern
  • Source: src/primitives/dialog/

Toast

  • Use when: Auto-dismissing notifications
  • Enable/Install: features = ["toast"]
  • Import/Invoke: use ratkit::{ToastManager, ToastLevel};
  • Minimal flow:
    1. Create ToastManager::new() in app state
    2. Add toasts via .success(), .error(), .info(), .warning()
    3. Call cleanup() before render
    4. Render with render_toasts()
  • Key APIs: ToastManager::new(), .add(), .success(), .error(), .cleanup()
  • Pitfalls: Must call cleanup() to remove expired; doesn't auto-expire
  • Source: src/primitives/toast/

TreeView

  • Use when: Hierarchical data with expand/collapse/selection
  • Enable/Install: features = ["tree-view"] (auto-enables widget-event)
  • Import/Invoke: use ratkit::{TreeNode, TreeView, TreeViewState, TreeNavigator};
  • Minimal flow:
    1. Build TreeNode hierarchy
    2. Create TreeView::new(nodes) with render_fn
    3. Create TreeViewState::new() for selection/expansion
    4. Use TreeNavigator for keyboard handling
  • Key APIs: TreeNode::new(), TreeView::new(), TreeViewState::new(), TreeNavigator::new()
  • Pitfalls: TreeViewState must persist; TreeNavigator handles all keyboard nav
  • Source: src/primitives/tree_view/

MarkdownWidget

  • Use when: Rendering markdown with syntax highlighting, TOC, themes
  • Enable/Install: features = ["markdown-preview"] (complex dependencies)
  • Import/Invoke: use ratkit::widgets::markdown_preview::{MarkdownWidget, ScrollState, SourceState, ...};
  • Minimal flow:
    1. Create state structs (ScrollState, SourceState, etc.) in app state
    2. Create MarkdownWidget::new(content, scroll, source, ...)
    3. Handle keyboard with handle_key()
    4. Render with ratatui
  • Key APIs: new(), handle_key(), handle_mouse(), .show_toc(), .show_scrollbar()
  • Pitfalls: Requires mouse capture enabled; state must persist across renders
  • Source: src/widgets/markdown_preview/widgets/markdown_widget/

FileWatcher

  • Use when: Detecting file/directory changes
  • Enable/Install: features = ["file-watcher"] (uses notify crate)
  • Import/Invoke: use ratkit::services::file_watcher::FileWatcher;
  • Minimal flow:
    1. Create FileWatcher::for_file() or FileWatcher::for_directory()
    2. Call watch(path)
    3. Poll check_for_changes() in event loop
    4. Get changes with get_changed_paths()
  • Key APIs: for_file(), for_directory(), watch(), check_for_changes(), get_changed_paths()
  • Pitfalls: Must poll regularly; get_changed_paths() clears queue; debounced (100ms/200ms)
  • Source: src/services/file_watcher/

HotkeyService

  • Use when: Centralized hotkey management with scope filtering
  • Enable/Install: features = ["hotkey-service"]
  • Import/Invoke: use ratkit::services::hotkey_service::{Hotkey, HotkeyRegistry, HotkeyScope};
  • Minimal flow:
    1. Create HotkeyRegistry::new()
    2. Register hotkeys with Hotkey::new(key, description).scope(scope)
    3. Set active scope with set_active_scope()
    4. Query with lookup(key, scope) in event loop
  • Key APIs: HotkeyRegistry::new(), register(), lookup(), set_active_scope()
  • Pitfalls: Uses &'static str for scopes; must handle crossterm events separately
  • Source: src/services/hotkey_service/

API Reference

Core Runtime

Component Key APIs
CoordinatorApp on_event(), on_draw(), on_layout_changed()
run run(), run_with_diagnostics()
Element id(), on_render(), on_keyboard(), on_mouse(), on_focus_gain(), on_focus_loss(), on_tick()
RunnerConfig tick_rate, layout_debounce, mouse_router_config

Primitives

Primitive Key APIs
Button new(), normal_style(), hover_style(), update_hover(), is_clicked()
Pane new(), with_icon(), with_padding(), with_uniform_padding(), border_style()
Dialog new(), info(), warning(), error(), success(), confirm(), buttons()
Toast ToastManager::new(), .add(), .success(), .error(), .cleanup()
TreeView TreeNode::new(), TreeView::new(), TreeViewState::new(), TreeNavigator::new()
Scroll calculate_scroll_offset()

Services

Service Key APIs
FileWatcher for_file(), for_directory(), watch(), check_for_changes(), get_changed_paths()
GitWatcher new(), with_config(), watch(), check_for_changes()
RepoWatcher new(), with_config(), watch(), check_for_changes(), get_change_set()
HotkeyRegistry new(), register(), lookup(), set_active_scope()

Common Pitfalls

Feature Flags

  1. No default features: Must explicitly enable every feature you use
  2. Cross-feature deps: tree-view enables widget-event; repo-watcher enables file-watcher and git-watcher
  3. Missing feature errors: "unresolved import" usually means missing feature flag

State Management

  1. StatefulWidget pattern: Complex widgets require persistent state in app struct
  2. Never create state in render: Always store widget state in app struct
  3. Weak references: Element registry stores weak refs - keep strong refs in app

Event Handling

  1. Return values: Return true when consuming events, false to propagate
  2. Mouse capture: Must enable crossterm mouse capture for interactions
  3. Poll services: Must call check_for_changes() regularly on watchers

Examples

  1. Feature flags required: Examples need their specific features: --features markdown-preview
  2. Just commands: Use just demo for interactive picker or just demo-* for specific demos

Optional

Additional Resources

  • Examples: 23 examples in examples/
  • Just commands: Run just help for all available commands
  • Build: just build or cargo build -p ratkit --all-features
  • Test: just test

Version

  • Current: 0.2.5
  • Rust: 1.70+

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 4f58a51. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 9 months ago

README badge

README badge for alpha-innovation-labs/opencode-rs-sdk/ratkit