For your agent to use aisling.

aisling.MD

Agent Guide: Using Aisling

Aisling is a Rust crate for embeddable terminal text effects. It is designed for TUI apps: it does not own the terminal or run its own event loop. Your app pulls frames from an iterator and renders those frames into your UI buffer.

Add The Crate

From crates.io:

cargo add aisling

Or in Cargo.toml:

[dependencies]
aisling = "0.1"

Minimal Use

use aisling::{Effect, EffectConfig, EffectKind};

let config = EffectConfig::default()
    .with_duration(80)
    .with_seed(42);

let effect = Effect::with_config(EffectKind::Matrix, "Hello from Aisling", config);

for frame in effect.iter() {
    // Render frame.cells() into your TUI buffer.
    // Or use frame.to_ansi_string() for quick terminal demos.
}

Rendering Frames

Each Frame is a fixed-size grid of styled Cell values.

for y in 0..frame.height() {
    for x in 0..frame.width() {
        let cell = frame.cell(x, y).unwrap();
        let ch = cell.ch;
        let fg = cell.colors.fg;
        let bg = cell.colors.bg;

        // Map ch, fg, and bg into your TUI renderer.
    }
}

Useful helpers:

let plain = frame.to_plain_string();
let ansi = frame.to_ansi_string();

Selecting Effects

Use the enum directly:

let effect = Effect::new(EffectKind::Wipe, "Loading...");

Or parse from a command string:

use std::str::FromStr;
use aisling::EffectKind;

let kind = EffectKind::from_str("laseretch").unwrap();

All effect names:

beams
binarypath
blackhole
bouncyballs
bubbles
burn
colorshift
crumble
decrypt
errorcorrect
expand
fireworks
highlight
laseretch
matrix
middleout
orbittingvolley
pour
print
rain
randomsequence
rings
scattered
slice
slide
smoke
spotlights
spray
swarm
sweep
synthgrid
thunderstorm
unstable
vhstape
waves
wipe

What The Effects Do

Effect	Behavior
beams	Horizontal and vertical beams reveal the text.
binarypath	Binary glyphs move into character positions.
blackhole	Text collapses toward a center point, then expands back out.
bouncyballs	Characters fall and bounce into place.
bubbles	Bubble-like particles float and pop into text.
burn	Fire, heat, and smoke reveal the final characters.
colorshift	Existing text cycles through a moving gradient.
crumble	Text breaks apart, drifts, and reforms.
decrypt	Cipher characters resolve into final text.
errorcorrect	Wrong characters correct themselves over time.
expand	Characters expand outward from the center.
fireworks	Characters launch and burst into final positions.
highlight	A bright highlight band sweeps across the text.
laseretch	A scanning laser etches the text into place.
matrix	Digital rain resolves into the final text.
middleout	Text reveals from the middle outward.
orbittingvolley	Orbiting launchers fire characters inward.
overflow	Rows overflow and slide before settling.
pour	Characters pour downward into place.
print	Text appears like it is being printed.
rain	Characters rain from above.
randomsequence	Characters appear in randomized order.
rings	Characters orbit in rings and then land.
scattered	Scattered characters move into final positions.
slice	Text halves slide in from opposite sides.
slide	Rows slide in with alternating direction.
smoke	Smoke-like particles reveal the text.
spotlights	Moving spotlights illuminate the text.
spray	Characters spray from an origin point into place.
swarm	Characters swarm around before settling.
sweep	A two-pass sweep reveals gray then colored text.
synthgrid	A synth-style grid dissolves into text.
thunderstorm	Rain and lightning reveal glowing text.
unstable	Text jitters, explodes, and reassembles.
vhstape	VHS glitch/noise distortions settle into text.
waves	Wave motion passes through the characters.
wipe	A directional wipe reveals the final text.

Configuration Cheatsheet

use aisling::{Color, EffectConfig, Gradient, GradientDirection};

let config = EffectConfig::default()
    .with_duration(120)
    .with_seed(7)
    .with_canvas_size(48, 8)
    .with_gradient(
        Gradient::new(vec![Color::rgb(255, 170, 60), Color::rgb(80, 110, 95)], 24),
        GradientDirection::Horizontal,
    );

Key fields:

Field	Use
duration	Number of animation frames.
hold_final_frames	Extra frames to keep the final text visible.
seed	Deterministic seed for repeatable animation.
gradient	Color palette for final/effect colors.
gradient_direction	Horizontal, vertical, diagonal, or radial color mapping.
easing	Global easing function for movement/reveal timing.
existing_color_handling	Preserve or ignore ANSI colors from input text.
no_color	Disable colors.
canvas_width, canvas_height	Fixed frame size.
tab_width	Tab expansion width.

Agent Notes

Use EffectKind::all() when you need to show every effect.

Use Effect::final_frame() when you only need the completed text state.

Use Effect::frames() for short demos or tests. Use Effect::iter() in real TUI loops to avoid holding all frames if you do not need them.

For quick local demos in this repository:

./run.sh list
./run.sh wipe "Hello"
./run.sh showcase --theme industrial