scrin-widgets

scrin-widgets is a plug-and-play Rust widget library for building Scrin-style TUIs with Scrin. It ships animated Aisling effects, ambient glyph fields, glowing gauges, signal panels, data surfaces, and frame-aware helpers that can be dropped into a normal Scrin app.

Install

From this repo:

[dependencies]
scrin-widgets = { path = "." }

From crates.io:

[dependencies]
scrin-widgets = "0.2.7"

This release targets scrin = "0.1.83".

Quick Use

use scrin::{Frame, widgets::{Paragraph, Widget}};
use scrin_widgets::{AislingExt, AislingPalette};

fn draw(frame: &mut Frame<'_>, tick: u64) {
    let area = frame.area();
    let palette = AislingPalette::dream();
    let block = palette.block("Aisling");
    let inner = block.inner(area);
    let buffer = frame.buffer();

    block.render(buffer, area);
    Paragraph::new("any Scrin widget can shimmer")
        .aisling()
        .tick(tick)
        .render(buffer, inner);
}

Scrin 0.1.83 Integration

AislingPalette now bridges directly into Scrin's theme layer:

use scrin::theme::{Theme, ThemeTokens};
use scrin_widgets::AislingPalette;

let palette = AislingPalette::cypherpunk();
let tokens: ThemeTokens = palette.into();
let theme: Theme = palette.theme();
let block = palette.block("theme-backed panel");

StreamPanel, List, TabBar, and Table include hit_regions(...) and render_with_interaction(...) helpers for Scrin frame metadata. StreamPanel, List, and Table also emit SelectableSpan and ScrollRowHit metadata so apps can use Scrin's hit testing, selectable text, and logical scroll-row APIs with these widgets. These helpers render through Frame, register metadata, and mark their areas dirty for presentation strategies such as PresentStrategy::MarkedDirty.

ScrinEffect and ScrinLoader adapt Scrin's EffectPlayer and LoaderPlayer APIs into normal Scrin widgets with AislingPalette, optional blocks, frame ticks, gradients, and render_with_interaction(...) helpers.

FrameStats renders Terminal::last_frame_timing(), Frame::diagnostics(), dirty-region counts, and interaction metadata counts in a compact Scrin widget. Use FrameStats::from_frame(frame, timing) inside a draw closure to build a live diagnostics panel.

Included Widgets

Aisling<W> wraps any Scrin Widget and applies animated shimmer, scanline, and edge-glow effects after the widget renders.

ScrinEffect renders Scrin/Aisling EffectKind animations through EffectPlayer with widget ergonomics.

ScrinLoader renders Scrin/Aisling LoaderKind progress displays through LoaderPlayer with widget ergonomics.

FrameStats renders frame timing, dirty-region, diagnostic, and interaction metadata counters for debugging Scrin presentation flow.

GlyphRain renders a deterministic matrix-like field for backgrounds and data streams.

NebulaGauge renders a glowing progress meter with a flowing fill.

SignalPanel renders a compact status panel with animated signal bars.

FlickerPanel renders text with per-character glitch and flicker effects.

Waveform renders an animated oscilloscope display (sine, square, sawtooth, triangle waves).

PulseRing renders expanding concentric rings from the center of an area.

Radar renders a rotating radar sweep with a fade trail.

OrbField renders floating animated particles (orbs).

NeonBorder renders an animated color-cycling border around any block.

StreamPanel renders streaming logs/code with optional line numbers and follow-tail behavior.

SplitPane computes horizontal or vertical panes with optional dividers.

List, TabBar, and Table render selectable data/navigation surfaces and can emit Scrin interaction metadata.

Sparkline, Gauge, Paragraph, StatusBar, and Bordered provide compact utility surfaces for dashboards and examples.

Examples

Run a static preview:

cargo run --example basic

Run the animated showcase:

cargo run --example showcase

Run the animated void orchard:

cargo run --example void_orchard

Run the animated starforge panel:

cargo run --example starforge

Run the full interactive showcase (all widgets, tabs, overlay):

cargo run --example showcase_all

In the showcase: 1-4 switch tabs, Tab/BackTab cycle, O toggles overlay, q/Esc quits.

Run the Scrin 0.1.83 flow demo:

cargo run --example scrin_flow

The flow demo shows TerminalOptions, PresentStrategy::MarkedDirty, frame diagnostics, palette/theme conversion, and interaction metadata helpers in one app.

Run the metadata probe demo:

cargo run --example metadata_flow

The metadata demo shows live HitRegion, SelectableSpan, and ScrollRowHit output for StreamPanel, List, and Table.

Run the Scrin effect/loader adapter demo:

cargo run --example effect_loader_flow

The effect/loader demo cycles Scrin's published EffectKind::all() and LoaderKind::all() lists through ScrinEffect and ScrinLoader.

Run the frame stats diagnostics demo:

cargo run --example frame_stats_flow

The frame stats demo shows FrameStats::from_frame(...), Frame::diagnostics(), Terminal::last_frame_timing(), timed panes, dirty regions, and interaction metadata counts in one live panel.

Package Hygiene

The crate manifest uses a Cargo package allow-list: Cargo.toml, README.md, src/**, and examples/**. Local session artifacts, build outputs, and other workspace files are not uploaded to crates.io.