toofan: Instructions file for Codex

AGENTS.md

Project context for AI coding assistants working on this repository.

Overview

Toofan is a terminal typing test written in Go. It uses Bubble Tea for the TUI and Lipgloss for styling. Everything runs offline — words, code snippets, themes, and user data are all local.

Build & Run

go build -o toofan .   # compile binary
go run .               # run without building
go vet ./...           # lint check before committing

There are no external services, databases, or network calls. User data lives in ~/.config/toofan/ as local JSON/JSONL files.

Project Structure

main.go                         Entry point. Initializes Bubble Tea program.
internal/
  game/
    game.go                     Core game logic: typing, backspace, stats, timer.
    storage.go                  All file I/O: config, results, PBs, backups.
  tui/
    model.go                    Bubble Tea model, Update loop, View dispatch.
    typing.go                   Typing screen: input handling, live WPM, progress bar.
    results.go                  Post-test results screen.
    profile.go                  Profile dashboard: overview, PBs, ranks, history, heatmap.
    text.go                     Text rendering: syntax coloring, word wrapping, cursor.
    picker.go                   Picker overlays: language, lesson, theme, duration.
  lang/
    lang.go                     Loads embedded word lists and code snippets from data/.
    data/<language>/            One directory per language.
      words.txt                 Word list (one word per line, english only).
      lessons/<topic>.go        Code lessons (hand-written, not generated).
  theme/
    theme.go                    Palette struct, All slice, Next/ByName helpers.
    <name>.go                   One file per theme. Each exports a single Palette var.

Architecture Rules

• game/ has zero UI dependencies. It must never import tui/, theme/, or lipgloss.
• tui/ reads game state through accessors (g.Text(), g.Input(), g.Errors()). It never touches game internals directly.
• All file I/O is centralized in storage.go. No file reads/writes anywhere else.
• lang/ uses embed.FS to bake data files into the binary at compile time. No runtime file system access for content.