FluffyUI AGENTS.md

AGENTS.md - Contribution Guide for FluffyUI

This document provides essential context for AI agents and contributors working on FluffyUI, a Go-based terminal UI framework with sub-cell graphics, reactive state, and accessibility support.

Project Overview

FluffyUI is a comprehensive terminal UI framework featuring:

• 28+ packages organized by responsibility
• 35+ widgets with consistent patterns
• Sub-cell graphics using Braille/Sextant/Quadrant rendering
• Reactive state via signals and computed values
• Two backends: tcell (terminal), sim (testing)
• Built-in accessibility with screen reader support
• Agent integration via MCP protocol

Go Version: 1.24+

---

Directory Structure

fluffyui/
├── runtime/          # Core app loop, render pipeline, message handling
├── widgets/          # 35+ reusable UI components
├── state/            # Reactive signals and computed values
├── animation/        # Tweens, springs, particle systems
├── graphics/         # Sub-cell canvas with shapes and curves
├── gpu/              # GPU canvas and drivers (software/OpenGL/Metal)
├── backend/          # Backend abstractions
│   ├── tcell/        # Real terminal (tcell v2)
│   └── sim/          # Simulation for testing
├── keybind/          # Keyboard routing and command registry
├── forms/            # Form validation and coordination
├── accessibility/    # Screen reader support, focus management
├── agent/            # Out-of-process agent server with MCP
├── recording/        # Asciicast and video export
├── audio/            # Music and SFX service
├── compositor/       # Screen buffer and ANSI rendering
├── theme/            # Theme management
├── style/            # Style system (colors, attributes)
├── toast/            # Toast notifications
├── scroll/           # Virtual scrolling utilities
├── effects/          # Visual effects (gradients, glow)
├── dragdrop/         # Drag-and-drop interfaces
├── terminal/         # Terminal abstraction (keys, mouse)
├── clipboard/        # Clipboard abstraction
├── markdown/         # Markdown parsing and highlighting
├── progress/         # Progress tracking
├── testing/          # Test helpers
├── examples/         # 19+ example applications
├── docs/             # Comprehensive documentation
└── scripts/          # Recording and agent tools