build

Files (9)

• SKILL.md
• architecture.rst · references/
• components.rst · references/
• fang.rst · references/
• layout.rst · references/
• patterns.rst · references/
• recipes.rst · references/
• styling.rst · references/
• testing.rst · references/

SKILL.md (first lines)

# Charm TUI Skill

Build correct, idiomatic terminal UIs with the Charm ecosystem.

---

## Import Paths — Anti-Hallucination Guard

> **WARNING:** Bubbletea, Bubbles, Lip Gloss, and Fang v2 moved to the `charm.land`
> vanity domain. **Do NOT use** `github.com/charmbracelet/{bubbletea,bubbles,lipgloss,fang}`
> — those are v0/v1. **Exception:** teatest v2 lives at
> `github.com/charmbracelet/x/exp/teatest/v2` (there is no `charm.land` teatest).

| Library         | Correct v2 Import Path                        |
|-----------------|-----------------------------------------------|
| Bubbletea       | `charm.land/bubbletea/v2`                     |
| Bubbles         | `charm.land/bubbles/v2/<name>`                |
| Lip Gloss       | `charm.land/lipgloss/v2`                      |
| Fang            | `charm.land/fang/v2`                          |
| teatest         | `github.com/charmbracelet/x/exp/teatest/v2`   |

Always alias bubbletea: `tea "charm.land/bubbletea/v2"`.

**Verify canonical API:** if the project's `go.mod` pins other versions or a symbol
differs from these references, check `go doc charm.land/bubbletea/v2 <Symbol>` (or
pkg.go.dev) instead of trusting the references. Do not silently upgrade the user's modules.

---

## Quick Start — Counter App

```go
package main

import (
	"fmt"
	"os"

	tea "charm.land/bubbletea/v2"
)

type model struct {
	count int
}

func (m model) Init() tea.Cmd {
	return nil
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyPressMsg:
		switch msg.String() {
		case "up", "k":
			m.count++
		case "down", "j":
			m.count--
		case "ctrl+c", "q":
			return m, tea.Quit  // tea.Quit — no parentheses
		}
	}
	return m, nil
}

func (m model) View() tea.View {
	s := fmt.Sprintf("Count: %d\n\nup/k: increment • down/j: decrement • q: quit\n", m.count)
	return tea.NewView(s)
}

func main() {
	if _, err := tea.NewProgram(model{}).Run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}
```

Key v2 patterns shown:
- `Init() tea.Cmd` — returns nil for no startup command
- `Update(tea.Msg) (tea.Model, tea.Cmd)` — type-switch on message
- `View() tea.View` — returns `tea.NewView(string)`, **not** a raw string
- `tea.Quit` — the function reference itself, **no parentheses**
- `tea.KeyPressMsg` — v2 key-press type (`tea.KeyMsg` is an interface matching press and release)
- `msg.String()` — easiest way to match key combinations like `"ctrl+c"`

---

## Core Concepts

### The Elm Architecture (Init / Update / View)
Every Bubbletea program is a Model implementing three methods. Init runs once at startup. Update handles every incoming message and returns a (possibly mutated) model plus an optional async Cmd. View renders the current state to a string, then wraps it in `tea.NewView()`.
→ See [references/architecture.rst](references/architecture.rst) for the full lifecycle, message types, and Cmd functions.

### Messages and Commands
`tea.Msg` is any event: key press, window resize, timer tick, HTTP response. `tea.Cmd` is an async I/O function (`func() tea.Msg`) that runs off the main loop and delivers its result as a message. Never block in Update — use a Cmd instead.
→ See [references/architecture.rst](references/architecture.rst)

### Bubbles Components
Bubbles provides ready-made components (textinput, list, table, viewport, spinner, progress, filepicker, help, and more). Each is an embeddable Model with its own `Update`/`View`. You delegate to them in your parent Update.
→ See [references/components.rst](references/components.rst) for all 14+ components with exact signatures.

### Lip Gloss Styling
Lip Gloss styles are **immutable** — every method returns a new Style. Chain calls, then call `.Render(text)` at the end. Use `lipgloss.Color("hex")` or named constants for colors.
→ See [references/styling.rst](references/styling.rst)

### Layout Composition
`lipgloss.JoinHorizontal` and `lipgloss.JoinVertical` place rendered string blocks side-by-side or stacked. `lipgloss.Place` centers content in a bounding box.
→ See [references/layout.rst](references/layout.rst)

### Composition Patterns
Three approaches for multi-component TUIs: flat (single model, state enum), model-stack (child models as struct fields), hybrid (stack + mode enum). Focus management uses Tab/Shift-Tab cycling.
→ See [references/patterns.rst](references/patterns.rst)

### Testing
`teatest` provides `NewTestModel`, `WaitFor`, and `RequireEqualOutput` for golden-file testing. VHS records `.tape` scripts for visual regression.
→ See [references/testing.rst](references/testing.rst)

### Fang CLI Polish
Fang wraps a Cobra command with styled help, errors, man pages, and shell completions via `fang.Execute(ctx, cobraCmd, opts...)`.

From nq-rdl/agent-extensions, CC-BY-4.0.

More from nq-rdl/agent-extensions