bubbletea-cinematic

bubbletea-cinematic

Cinematic rendering primitives and animated widgets for Bubble Tea TUIs.

Particles, shader-style backgrounds, braille subpixel rendering, compositing, scene transitions, graph animations, and agent dashboards — all in pure Go.

Why?

Bubble Tea is excellent for terminal app architecture. bubbletea-cinematic adds the missing visual layer: motion, depth, particles, transitions, and high-density terminal rendering primitives.

Use it when your CLI should feel alive without becoming a heavy GUI.

Features

• Particles & Physics — Gravity, drag, trails, attraction, object pooling.
• Shader Backgrounds — Plasma, void, noise, pulse, gradient. Shader-style animated terminal backgrounds.
• Braille Rendering — 2x4 subpixel resolution per character. Draw circles, lines, spirals at high fidelity.
• Cell Buffer Compositor — Z-index layering, opacity blending, multi-layer compositing.
• Scene Management — Scene lifecycle, transitions (fade, slide, dissolve, wipe, particle burst).
• Timeline & Keyframes — Sequence events, animate properties with easing curves.
• Easing Library — 30+ easing functions: quad, cubic, elastic, bounce, back, and utilities.
• Tween Engine — Animate any float value. Sequences, groups, loops, reverse.
• Graph Widget — Force-directed layout, node animations, packet flow visualization.
• Pulse Widget — Concentric ring animations with configurable colors and intensity.
• Background Widget — Drop-in animated shader backgrounds for any Bubble Tea app.
• Agent Dashboard — AI agent visualization: state machine, memory ring, neural graph, metrics.

Install

go get github.com/OnlineChefGroep/bubbletea-cinematic@latest

Quick Start

package main

import (
    "log"

    tea "github.com/charmbracelet/bubbletea"
    "github.com/OnlineChefGroep/bubbletea-cinematic/widget"
)

func main() {
    p := tea.NewProgram(
        widget.NewPlasmaBackground(80, 24),
        tea.WithAltScreen(),
    )
    if _, err := p.Run(); err != nil {
        log.Fatal(err)
    }
}

Examples

Run any example with:

go run examples/<name>/main.go

Packages

Architecture

                    +-----------+
                    |  widget/  |  Ready-to-use components
                    +-----+-----+
                          |
           +--------------+--------------+
           |              |              |
     +-----+-----+  +----+----+  +------+-----+
     |  motion/   |  | render/ |  |   scene/   |
     | particles  |  | buffer  |  | transitions|
     | physics    |  | braille |  | timeline   |
     | easing     |  | shader  |  | ticker     |
     | tween      |  | compos. |  | manager    |
     +-----+------+  +----+----+  +------+-----+
           |              |              |
           +--------------+--------------+
                          |
                    +-----+-----+
                    | internal/ |  Math, color utilities
                    +-----------+

Data flow:

1. scene.Ticker produces frame ticks with delta time
2. motion package updates physics, particles, tweens
3. render package draws to buffers (cell or braille)
4. render.Compositor layers buffers with z-order
5. scene.Manager handles scene transitions
6. Bubble Tea renders the final string to the terminal

Performance

This library is designed for smooth terminal animation and allocation-aware rendering. Run local validation with:

go test ./...
go test -bench=. -benchmem ./...

Documentation

• Architecture
• Examples
• Performance
• API Overview
• Agent Dashboard

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT — see LICENSE.

Built for terminal artists who refuse to be boring.