bubbletea

Bubble Tea

Write current, compiling Bubble Tea v2 code (pinned to v2.0.x on the charm.land/*/v2 import paths) and refuse the v1/beta patterns the model remembers from training. The body is the load-bearing 20%: the Elm mental model and one verified example per concept. Everything enumerable — the full Bubbles catalog, the key/mouse taxonomy, styling, streaming, testing, migration — lives in references/. Open the matching reference before writing nontrivial code in that area.

Imports — the whole stack is on charm.land

Every Charm framework package lives on charm.land/*/v2. The most common v2 mistake is importing lipgloss or bubbles from the old github.com/charmbracelet/… path while using charm.land bubbletea — that pulls two incompatible trees into one build and fails to compile. Use these paths; only the x/* helpers stay on github.com:

import (
	tea "charm.land/bubbletea/v2"
	"charm.land/lipgloss/v2"           // NOT github.com/charmbracelet/lipgloss
	"charm.land/bubbles/v2/viewport"   // list, table, textinput, textarea, spinner, … under bubbles/v2/<c>
	"charm.land/glamour/v2"
	"github.com/charmbracelet/x/ansi"  // width/wrap helpers — these have no charm.land alias
)

Mental model — The Elm Architecture is the whole framework

Bubble Tea is not a widget toolkit you poke at; it is one mandatory loop. You give the runtime a Model (your immutable state) and three methods, and it owns everything else:

• Init returns an optional first Cmd.
• Update receives a Msg, returns a (possibly changed) Model and an optional Cmd.
• View renders the Model to a tea.View.

The runtime calls Update for every message, then View, and paints the result. This is MVU (Model-View-Update). The entire discipline follows from it:

• Mutate state only inside Update. Never from View, from a Cmd body, or from a goroutine. Update is the single writer; everything else races the render loop.
• Never block in Update. It runs on the render path. Do I/O — network, disk, subprocess, a timer — inside a Cmd, which the runtime runs in its own goroutine and whose result comes back as a Msg.
• Models flow by value. Update takes the Model by value, mutates the local copy, and returns it. Bubbles (sub-components) work the same way — you reassign what their Update returns.