@cleocode/animations

@cleocode/animations

Unicode terminal animations for the cleo CLI and CleoOS — woven on the LOOM, gated by LAFS.

Provides four primitive surfaces, each gated by a single AnimateContext so the LAFS protocol invariant ("JSON output is the default; human rendering requires explicit opt-in") holds uniformly:

• 18 generic braille spinners — frame-cycled loaders ported from unicode-animations (MIT, Gunnar Gray)
• 9 canon spinner aliases — workshop vocabulary (looming, weaving, heartbeat, …) on the same frame data
• 3 progress bar styles — tapestry, cascade, refinery (canon-themed segmented gauges)
• 4 sparks — one-shot accents (awaken, sweep, cascade, weave)

Install

pnpm add @cleocode/animations
# or
npm install @cleocode/animations

ESM-only. Requires Node ≥ 22.

Quick start

Spinner during async work — createSpinnerHandle

createSpinnerHandle is the canonical owner of \r writes for this package. It manages the timer, hides/restores the cursor, installs an exit handler so Ctrl-C doesn't leave a hidden cursor, and routes everything through the LAFS render gate. Calling process.stdout.write of a string starting with \r outside this package is a contract violation — always go through the handle.

import { resolveOutputFormat } from '@cleocode/lafs';
import { createAnimateContext, createSpinnerHandle } from '@cleocode/animations';

const ctx = createAnimateContext({
  flagResolution: resolveOutputFormat({ humanFlag: true }),
});

const spinner = createSpinnerHandle(ctx, 'looming', 'Weaving tasks…');
spinner.start();
try {
  await doWork();
  spinner.stop('✔ Tapestry complete.');
} catch (err) {
  spinner.stop();
  throw err;
}

Under --json / --quiet / non-TTY / NO_COLOR the handle is a frozen no-op and emits zero output — call sites stay branch-free.

Progress bar with a known ratio

import { renderProgressBar } from '@cleocode/animations';

function tick(done: number, total: number) {
  const ratio = done / total;
  const bar = renderProgressBar('refinery', ratio, 36);
  process.stdout.write(`\r\x1B[2K  ${bar}  ${done}/${total}`);
}

One-shot spark on success

import { sparks } from '@cleocode/animations';

async function playSpark(name: 'awaken' | 'sweep' | 'cascade' | 'weave') {
  const { frames, interval } = sparks[name];
  for (const f of frames) {
    process.stdout.write(`\r\x1B[2K  ${f}`);
    await new Promise(r => setTimeout(r, interval));
  }
  process.stdout.write('\n');
}

await shipRelease();
await playSpark('cascade');

LAFS-aware rendering — AnimateContext

Every primitive routes through an AnimateContext so the package obeys the LAFS protocol uniformly. The context is pure data — no I/O, no timers — derived from the LAFS FlagResolution plus environment signals.

import { resolveOutputFormat } from '@cleocode/lafs';
import { createAnimateContext, createSpinnerHandle } from '@cleocode/animations';

const flags = resolveOutputFormat({ humanFlag: true });
const ctx = createAnimateContext({ flagResolution: flags });

// Hand `ctx` to any primitive — they all become no-ops when `ctx.enabled === false`.
const spinner = createSpinnerHandle(ctx, 'looming', 'Loading…');

if (!ctx.enabled) {
  // ctx.reason ∈ 'format-json' | 'quiet' | 'no-tty' | 'no-color' | 'enabled'
  console.log(`silent: ${ctx.reason}`);
}

Signal	Source	Effect	reason
format !== 'human'	LAFS flags	Disable (machine output)	format-json
quiet === true	LAFS flags	Disable (script-friendly)	quiet
!isTTY	process.stdout.isTTY	Disable (piped/redirected)	no-tty
NO_COLOR set	process.env.NO_COLOR	Disable (no-color.org)	no-color

SILENT_CONTEXT is exported as a frozen always-disabled context for tests and libraries that want to opt out without constructing a full LAFS resolution.

Spinner registry

Generic — 18 braille loaders

Name	Frames	Interval	Name	Frames	Interval
braille	10	80ms	cascade	14	60ms
braillewave	8	100ms	columns	26	60ms
dna	12	80ms	orbit	8	100ms
scan	10	70ms	breathe	17	100ms
rain	12	100ms	waverows	16	90ms
scanline	6	120ms	checkerboard	4	250ms
pulse	5	180ms	helix	16	80ms
snake	16	80ms	fillsweep	11	100ms
sparkle	6	150ms	diagswipe	16	60ms

Canon — 9 workshop aliases

Canon name	→ Generic	Cleo lore role
looming	helix	Twin strands weaving — task on the LOOM
weaving	braillewave	Pattern threading across columns
heartbeat	breathe	Organic in-out pulse — Hearth presence
awakening	pulse	Radial bloom — first dream / cleo init
sweeping	scan	Left→right beam — BRAIN integrity Sweep
watching	orbit	Circular sentinel — sentient daemon tick
cascade	cascade	Diagonal fall — command-success accent
tapestry	waverows	Multi-row sinusoidal — wave of tasks shipping
refinery	columns	Filling stages — memory promotion pipeline

Canon entries are aliases, not copies — they reference the same Spinner objects as the generic registry. Renaming a generic spinner automatically updates the canon view. The mapping is exposed as CANON_TO_GENERIC and resolveSpinner(name) accepts either form.

Progress bars

renderProgressBar(style, ratio, width) returns a fixed-width string. Three canon styles:

Style	Characters	Feel
tapestry	░ ▒ ▓ █	Coarse blocks — woven cloth filling cell-by-cell
cascade	▏ ▎ ▍ ▌ ▋ ▊ ▉ █	1/8 gradient steps — smooth waterfall edge
refinery	⠀ ⡀ ⡄ ⡆ ⡇ ⣇ ⣧ ⣷ ⣿	Braille block stages — BRAIN memory promotion pipeline

Inputs outside [0, 1] are clamped. width ≤ 0 returns ''.

Sparks — one-shot accents

import { sparks, sparkDurationMs } from '@cleocode/animations';

sparkDurationMs('cascade'); // → ~980ms (frames * interval)

Spark	Frames	Duration	Played on
awaken	13 × 90ms	~1.17s	cleo init · first dream · sentient wake
sweep	7 × 80ms	~560ms	BRAIN integrity sweep complete
cascade	14 × 70ms	~980ms	Release shipped · task complete
weave	18 × 70ms	~1.26s	Playbook stage transition · CANT directive accepted

Browser demo

A self-contained vitrine page ships at scripts/demo.html. Open it in any browser to preview every spinner, canon alias, progress style, and spark animating live, with API reference tables and code samples.

# From an npm install
open node_modules/@cleocode/animations/scripts/demo.html        # macOS
xdg-open node_modules/@cleocode/animations/scripts/demo.html    # Linux

# From the cleo monorepo checkout
open packages/animations/scripts/demo.html                       # macOS
xdg-open packages/animations/scripts/demo.html                   # Linux

The page is fully self-contained (no build step, no fetch, no node_modules runtime requirement) so it can be emailed, dropped into a slide deck, or hosted as a static asset for design reviews.

Terminal demo

npx cleocode-animations                  # cycle through generic + canon spinners
npx cleocode-animations looming          # preview one spinner (generic OR canon)
npx cleocode-animations spark cascade    # play one spark and exit
npx cleocode-animations progress         # loop through all 3 progress styles

npx cleocode-animations --list           # full listing — spinners + sparks + progress
npx cleocode-animations --list-canon     # canon aliases only
npx cleocode-animations --list-sparks    # sparks only
npx cleocode-animations --list-progress  # progress styles only

API surface

Spinners

Export	Type
spinners	Record<BrailleSpinnerName, Spinner>
canonSpinners	Record<CanonSpinnerName, Spinner>
CANON_TO_GENERIC	Record<CanonSpinnerName, BrailleSpinnerName>
resolveSpinner(name)	(string) => Spinner | undefined
gridToBraille(grid)	(boolean[][]) => string
makeGrid(rows, cols)	(number, number) => boolean[][]
Spinner	{ frames: readonly string[]; interval: number }
BrailleSpinnerName · CanonSpinnerName	TS string-literal unions

SpinnerHandle (canonical \r owner)

Export	Type
createSpinnerHandle(ctx, name, label, options?)	(AnimateContext, name, string, SpinnerHandleOptions?) => SpinnerHandle
SpinnerHandle	{ start(); stop(finalLine?); update(label); enabled: boolean }
SpinnerHandleOptions	{ delayMs?: number } — defaults to 150

AnimateContext

Export	Type
createAnimateContext(input)	(AnimateContextInput) => AnimateContext
SILENT_CONTEXT	Frozen AnimateContext — always disabled
AnimateContext	{ enabled, reason, inputs }
AnimateContextInput	{ flagResolution, isTTY?, noColor? }
FlagResolutionLike	{ format: 'json' | 'human'; quiet: boolean }

Progress + Sparks

Export	Type
progressBars	Record<ProgressBarStyle, ProgressBarRenderer>
renderProgressBar(style, ratio, width)	(style, number, number) => string
ProgressBarStyle	'tapestry' | 'cascade' | 'refinery'
sparks	Record<SparkName, Spark>
sparkDurationMs(name)	(SparkName) => number
SparkName	'awaken' | 'sweep' | 'cascade' | 'weave'

Custom spinners

Every animation here is built from two primitives — compose your own:

import { gridToBraille, makeGrid } from '@cleocode/animations';

const grid = makeGrid(4, 4);
grid[0][0] = true;
grid[1][1] = true;
grid[2][2] = true;
grid[3][3] = true;

console.log(gridToBraille(grid)); // diagonal braille pattern

makeGrid(rows, cols) returns a boolean[][]. Set cells to true to raise braille dots. gridToBraille(grid) packs them into a braille string (2 dot columns per character, U+2800 base).

License

MIT — dual copyright:

• © 2024 Gunnar Gray (original unicode-animations project)
• © 2026 CLEO Code (@cleocode/animations fork)

See LICENSE.