# 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:
```toml
[dependencies]
scrin-widgets = { path = "." }
```
From crates.io:
```toml
[dependencies]
scrin-widgets = "0.2.7"
```
This release targets `scrin = "0.1.83"`.
## Quick Use
```rust
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:
```rust
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:
```sh
cargo run --example basic
```
Run the animated showcase:
```sh
cargo run --example showcase
```
Run the animated void orchard:
```sh
cargo run --example void_orchard
```
Run the animated starforge panel:
```sh
cargo run --example starforge
```
Run the full interactive showcase (all widgets, tabs, overlay):
```sh
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:
```sh
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:
```sh
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:
```sh
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:
```sh
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.