Crate libshimmer 

Animated status lines for terminal UIs, paced by the host’s work.

A Shimmer is one running animation, made from a Recipe of stock::ROSTER. It dresses a caption, such as “Working”, and paints the status line’s lead (a mark of glyphs, the caption’s letters, and a tail of cells after them) over a backdrop of background colors. It also paints the bullet in front of a running sub-task, such as a tool call.

The host drives a shimmer with commands, each holding until the next replaces it: Shimmer::show sets the caption, Shimmer::set_spell what the host is doing, and Shimmer::set_intensity how hard it works. Each frame, the host passes the time elapsed since the previous frame to Shimmer::advance, which runs whole ticks of TICK, and draws the Row that Shimmer::status paints. Paint depends only on the recipe, the seed, the commands so far, the Palette, and the Motion: libshimmer reads no clock or environment and keeps no global state.

A host that learns of work in lumps can smooth them with a Reservoir, and a picker can preview a recipe by playing the script. The ratatui feature converts a row into ratatui spans and lays its backdrop into a ratatui buffer.

use std::time::Duration;

use libshimmer::{Glyphs, Intensity, Motion, Palette, Rgb, Shimmer, Spell, stock};

let recipe = stock::named("Lava Lamp").expect("a stock recipe");
let mut shimmer: Shimmer = Shimmer::new(recipe, 7, Glyphs::BASE)?;
shimmer.set_spell(Spell::Busy);
shimmer.show("Compiling");
shimmer.set_intensity(Intensity::new(0.6));
shimmer.advance(Duration::from_millis(100));
let palette = Palette { fg: Rgb(208.0, 208.0, 208.0), bg: Rgb(21.0, 21.0, 21.0) };
let row = shimmer.status(palette, Motion { mark: true, letters: true });
let lead: String = row.cells().map(|(symbol, _)| symbol).collect();
assert_eq!(lead, "● Compiling");

Modules

script

The preview script: a canned bout and the rest after it, playing in a loop, with which a picker previews a recipe.

stock

The stock recipes.

Structs

Glyphs

Glyph repertoires beyond the base set every target terminal draws: those a terminal draws, or those a recipe needs.

Ink

The paint of one cell. Unset colors are the terminal’s defaults, and an unset glyph keeps the text beneath.

Intensity

How hard the host works, measuring whatever the host chooses: at least 0, where Intensity::BRISK is the most a stage shows linearly.

Motion

Whether the mark and the letters may move.

NarrowStr

Text holding no grapheme wider than one cell.

Palette

The terminal’s default colors.

Recipe

A stock animation: its picker entry, what it needs of a host, and how to start its shader.

Reservoir

Turns lumps of work, such as a burst of tokens, into a flow that drains each lump over four seconds. A host converts the flow into an Intensity by its own measure.

Rgb

A 24-bit color whose channels stay fractional until they reach the terminal.

Row

A status line’s lead as painted, and the backdrop beneath it.

Shimmer

One recipe’s shader running on its own stage and clock: what a host holds. Shimmer alone is Shimmer<Wide>.

Unfit

Why a recipe cannot load for a host: glyphs the terminal lacks, or captions wider than the recipe paints well.

Enums

Narrow

Graphemes one cell wide: captions arrive checked, as NarrowStr.

Spell

What the host is doing.

Wide

Graphemes one or two cells wide: captions arrive as &str.

Constants

STALE

A gap between frames longer than this advances a shimmer by one tick, as after a pause in drawing.

TICK

One tick of shimmer time; a host that draws every tick schedules frames this far apart.

Traits

Gauge

The widest grapheme a shimmer’s captions may hold, fixed by the host in the shimmer’s type. Sealed: Wide and Narrow are the only gauges.