Metaspartan Go Tui

metaspartan-go-tui

Scaffold Go TUIs with github.com/metaspartan/gotui/v5 — a tcell v3-based immediate-mode library with a rich widget set, true-color support, and first-class SSH server support.

This skill is self-contained: use the instructions, local reference pages, and templates in this directory without consulting anything else.

When to Use This Skill

Library Identity

5-Minute Hello World

package main

import (
    "log"
    ui "github.com/metaspartan/gotui/v5"
    "github.com/metaspartan/gotui/v5/widgets"
)

type Hello struct{ *widgets.Paragraph }

func (h *Hello) HandleEvent(e ui.Event) bool {
    if e.Type == ui.KeyboardEvent && e.ID == "<Space>" {
        h.Text = "Pressed!"
        return true
    }
    return false
}

func main() {
    app := ui.NewApp()
    app.SetRoot(&Hello{widgets.NewParagraph()}, true)
    log.Fatal(app.Run())
}

Run: go run . Quit: q or <C-c>.

Full scaffold: assets/templates/helloworld.go.

API Style: Pick One

Rule of thumb: start with OO. Switch to Backend-only when you need multi-instance support (e.g. SSH servers).

→ See references/api-styles.md for the full decision tree.

Architecture: Three Building Blocks

1. Block — every widget embeds this. Provides borders, titles, padding, Inner rectangle math. Custom widgets start here.
2. Buffer + Cell{rune, style} — the rendering surface. Render() builds a union-sized buffer, asks each drawable to fill it, then flushes to tcell in one pass. No diffing, no flicker.
3. Application / Backend — the host. Application wraps a single Backend + root widget + focus widget + event loop. NewBackend is the per-instance variant used for SSH.

→ See references/architecture.md.

Layout: Three Strategies

For 90% of dashboards, Grid is the right answer. Ratio 1.0/8 + 3.0/8 + ... sums to 1.0 for clarity (auto-normalized otherwise).

→ See references/layout.md.

Events

gotui translates raw tcell keys into stable string IDs so your widget code never depends on tcell:

func (w *MyWidget) HandleEvent(e ui.Event) bool {
    switch e.Type {
    case ui.KeyboardEvent:
        switch e.ID {
        case "j", "<Down>": w.cursor++; return true
        case "k", "<Up>":   w.cursor--; return true
        }
    case ui.MouseEvent:
        m := e.Payload.(ui.Mouse)
        if e.ID == "<MouseLeft>" { w.activate(m.X, m.Y); return true }
    }
    return false
}

→ See references/events.md for the full ID table.

Styling

Flat ui.Style{Fg, Bg, Modifier} — no chain like lipgloss.

ui.NewStyle(ui.ColorCyan, ui.ColorBlack, ui.ModifierBold)
ui.NewRGBColor(255, 100, 50)
ui.HexToColor("#ff6432")
ui.GenerateGradient(ui.ColorRed, ui.ColorBlue, 16)

Inline DSL inside Paragraph.Text:

Hello [world](fg:red,mod:bold)!

Global theme singleton: ui.Theme.Paragraph.Text.Fg = ui.ColorWhite — simple but stateful.

→ See references/styling.md.

Widget Catalog (27 widgets)

→ See references/widgets-catalog.md for full reference.

Note: avoid the bundled brand-specific logo widget in product templates. Use your own ASCII art or a Paragraph with a custom title instead.

Common Patterns

Animated dashboard

go func() {
    ticker := time.NewTicker(100 * time.Millisecond)
    for range ticker.C {
        sparkline.Data = append(sparkline.Data[1:], newSample())
        ui.Render(grid)
    }
}()

Headless PNG (for docs)

if len(os.Args) > 1 && os.Args[1] == "-screenshot" {
    grid.SetRect(0, 0, 120, 40)
    ui.SaveImage("screenshot.png", 120, 40, grid)
    return
}

→ See references/screenshot-mode.md.

SSH server (multi-tenant)

ssh.Handle(func(sess ssh.Session) {
    tty, _ := newSessionTTY(sess)
    app, _ := ui.NewBackend(&ui.InitConfig{CustomTTY: tty})
    // ... render per-session dashboard ...
})
ssh.ListenAndServe(":2222", nil, ssh.HostKeyFile("hostkey"))

→ See assets/templates/sshserver.go and references/ssh-server.md.

Files in This Skill

techstack/metaspartan-go-tui/
├── SKILL.md                      ← you are here
├── references/
│   ├── architecture.md           Drawable/Block/Buffer/Application internals
│   ├── api-styles.md             Application OO vs Functional vs Backend-only
│   ├── events.md                 Full canonical key ID table
│   ├── styling.md                Theme, Style, inline DSL, gradients
│   ├── layout.md                 SetRect / Grid / Flex decision tree
│   ├── widgets-catalog.md        All 27 widgets with usage snippets
│   ├── ssh-server.md             Per-session Backend + Tty adapter pattern
│   └── screenshot-mode.md        -screenshot flag + SimulationScreen
└── assets/
    ├── spinner-frames.md         17 ready-made spinner frame sets
    └── templates/
        ├── helloworld.go         Minimum runnable (Application OO)
        ├── dashboard.go          Multi-widget Grid + ticker (Functional)
        └── sshserver.go          Per-session SSH TUI (Backend-only)

Quick Recipe

For most agents, the workflow is:

1. Identify the UI: list of widgets, layout, event model.
2. Pick the API style using the table above.
3. Copy a template from assets/templates/ into the user's Go application as a starting point, then adapt it to that app's package layout, module path, state model, and commands. Do not run templates in-place from the skill directory.
4. Add widgets via references/widgets-catalog.md.
5. Wire events via the ID table in references/events.md.
6. Style with the patterns in references/styling.md.
7. (Optional) Add SSH support via assets/templates/sshserver.go.