GitHub - ccheshirecat/flywheel: A high-performance, Rust-native rendering engine purpose-built for streaming LLM outputs at 60+ FPS without tearing, flickering, or input lag.

[dependencies]
flywheel-compositor = "0.1"

use flywheel::{Engine, StreamWidget, Rect, Rgb};

fn main() -> std::io::Result<()> {
    let mut engine = Engine::new()?;
    let mut stream = StreamWidget::new(Rect::new(0, 0, engine.width(), engine.height()));

    // Simulate LLM streaming
    for token in ["Hello, ", "world! ", "This ", "is ", "Flywheel."] {
        stream.set_fg(Rgb::new(0, 255, 128)); // Green text
        
        // Just push. The engine handles Fast/Slow path automatically.
        stream.push(&engine, token);
        
        std::thread::sleep(std::time::Duration::from_millis(100));
    }

    // Event loop
    while engine.is_running() {
        for event in engine.poll_input() {
            match event {
                flywheel::InputEvent::Key { code: flywheel::KeyCode::Esc, .. } => engine.stop(),
                _ => {}
            }
        }
    }

    Ok(())
}

cargo run --example streaming_demo --release

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Input Actor   │────▶│  Main Thread    │────▶│ Renderer Actor  │
│  (crossterm)    │     │  (Your Code)    │     │    (stdout)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
    Keyboard            Buffer Updates           ANSI Sequences
    Mouse Events        Widget Logic             Diff Output
    Resize              State Management         Cursor Control

let result = stream.append("x");

match result {
    AppendResult::FastPath { row, start_col, .. } => {
        // Character appended within viewport, no wrapping.
        // Emit: MoveTo(row, col) + SetColor + PrintChar
        // Cost: ~20 bytes to stdout
    }
    AppendResult::SlowPath => {
        // Wrapping or scrolling required.
        // Full frame rendered via diffing engine.
        // Cost: ~200 bytes to stdout (only changed cells)
    }
}

let mut raw_output = Vec::new();
stream.append_fast_into("x", &mut raw_output);
engine.write_raw(raw_output); // Sends RawOutput command to Renderer

// Initialization
let mut engine = Engine::new()?;                    // Default config
let mut engine = Engine::with_config(config)?;     // Custom FPS, mouse, etc.

// Dimensions
engine.width();   // Terminal columns
engine.height();  // Terminal rows

// Event Loop
engine.is_running();                                // Check if still alive
engine.poll_input();                                // Non-blocking: Vec<InputEvent>
engine.input_receiver().recv_timeout(duration);     // Blocking: for event-driven loops

// Rendering
engine.buffer_mut();        // Get mutable reference to the Next buffer
engine.request_update();    // Send buffer to Renderer (diff-based)
engine.request_redraw();    // Send buffer to Renderer (full redraw)
engine.write_raw(bytes);    // Bypass buffer, write ANSI directly (Fast Path)

// Lifecycle
engine.stop();              // Signal shutdown

let mut stream = StreamWidget::new(Rect::new(x, y, width, height));

// Styling
stream.set_fg(Rgb::new(255, 128, 0));  // Orange text
stream.set_bg(Rgb::new(20, 20, 20));   // Dark background
stream.set_bold(true);

// Content (Recommended API)
stream.push(&engine, "Hello");          // Automatic Fast/Slow path handling
stream.newline();
stream.clear();

// Low-level API (for advanced use cases)
stream.append("text");                  // Returns AppendResult, manual handling
stream.append_fast_into("x", &mut buf); // Manual Fast Path with raw output

// Scrolling (Sticky Scroll: auto-scroll only if at bottom)
stream.scroll_up(lines);
stream.scroll_down(lines);

// Rendering
stream.render(&mut buffer);             // Write to Buffer
stream.needs_redraw();                  // Check if dirty

let mut buffer = Buffer::new(80, 24);

buffer.set(x, y, Cell::new('A').with_fg(Rgb::RED));
buffer.get(x, y);                      // Option<&Cell>
buffer.draw_text(x, y, "text", fg, bg);
buffer.fill_rect(x, y, w, h, cell);
buffer.clear();

match event {
    InputEvent::Key { code, modifiers } => { /* KeyCode::Char, Esc, Enter, etc. */ }
    InputEvent::MouseClick { x, y, button } => { /* Left, Right, Middle */ }
    InputEvent::MouseScroll { x, y, delta } => { /* +1 up, -1 down */ }
    InputEvent::Resize { width, height } => { /* Terminal resized */ }
    InputEvent::Shutdown => { /* SIGTERM or similar */ }
    _ => {}
}

use flywheel::{TextInput, Widget, Rect};

let mut input = TextInput::new(Rect::new(0, 23, 80, 1));

// Configure
input.set_content("Initial text");
input.set_focused(true);

// Handle input events
if input.handle_input(&event) {
    // Event was consumed by the widget
}

// Render
input.render(buffer);

// Get content
let text = input.content();

use flywheel::{StatusBar, Widget, Rect};

let mut status = StatusBar::new(Rect::new(0, 0, 80, 1));
status.set_all("Flywheel", "v2.0", "60 FPS");

// Or set individually
status.set_left("App Name");
status.set_center("Status");
status.set_right("12:34");

status.render(buffer);

use flywheel::{ProgressBar, Widget, Rect, ProgressStyle};

let mut progress = ProgressBar::new(Rect::new(0, 5, 60, 1));
progress.set_progress(0.5);  // 50%
progress.set_label("Loading");
progress.increment(0.1);     // +10%

progress.render(buffer);

pub trait Widget {
    fn bounds(&self) -> Rect;
    fn set_bounds(&mut self, bounds: Rect);
    fn render(&self, buffer: &mut Buffer);
    fn handle_input(&mut self, event: &InputEvent) -> bool;
    fn needs_redraw(&self) -> bool;
    fn clear_redraw(&mut self);
}

use flywheel::{Engine, TickerActor, InputEvent, KeyCode};
use crossbeam_channel::select;
use std::time::Duration;

let engine = Engine::new()?;
let ticker = TickerActor::spawn(Duration::from_micros(16_666)); // 60 FPS

while engine.is_running() {
    select! {
        recv(engine.input_receiver()) -> result => {
            if let Ok(event) = result {
                match event {
                    InputEvent::Key { code: KeyCode::Esc, .. } => engine.stop(),
                    _ => handle_input(event),
                }
            }
        }
        recv(ticker.receiver()) -> _ => {
            // Tick: generate content, update animations
            generate_content(&mut stream);
            stream.render(engine.buffer_mut());
            engine.request_update();
        }
    }
}

ticker.join();

use crossbeam_channel::RecvTimeoutError;
use std::time::Duration;

let target_fps = Duration::from_micros(16_666); // 60 FPS
let mut last_tick = Instant::now();

while engine.is_running() {
    let timeout = target_fps.saturating_sub(last_tick.elapsed());
    
    match engine.input_receiver().recv_timeout(timeout) {
        Ok(event) => {
            // Handle input IMMEDIATELY
            handle_input(event);
            redraw_ui(&mut engine);
            engine.request_update();
        }
        Err(RecvTimeoutError::Timeout) => {
            // Tick: generate content, update animations
            last_tick = Instant::now();
            generate_content(&mut stream);
            stream.render(engine.buffer_mut());
            engine.request_update();
        }
        Err(_) => break,
    }
}

#include "flywheel.h"

int main() {
    FlywheelEngine* engine = flywheel_engine_new();
    FlywheelStream* stream = flywheel_stream_new(0, 0, 80, 24);

    flywheel_stream_set_fg(stream, 0, 255, 128);
    flywheel_stream_append(stream, "Hello from C!");
    flywheel_stream_render(stream, flywheel_engine_buffer(engine));
    flywheel_engine_request_update(engine);

    // Event loop...

    flywheel_stream_destroy(stream);
    flywheel_engine_destroy(engine);
    return 0;
}

cargo bench --bench cell_benchmark
cargo bench --bench diff_benchmark
cargo bench --bench rope_benchmark
cargo bench --bench comparison_benchmark  # Flywheel vs Ratatui