zcatui/CLAUDE.md

zcatui - TUI Library para Zig

IMPORTANTE PARA CLAUDE: Lee la sección "PROTOCOLO DE INICIO" antes de hacer cualquier cosa.

---

PROTOCOLO DE INICIO (LEER PRIMERO)

Paso 1: Leer normas del equipo

/mnt/cello2/arno/re/recode/TEAM_STANDARDS/LAST_UPDATE.md

Este archivo contiene los cambios recientes en las normas de trabajo. Léelo para detectar actualizaciones.

Paso 2: Leer normas completas si es necesario

/mnt/cello2/arno/re/recode/TEAM_STANDARDS/NORMAS_TRABAJO_CONSENSUADAS.md
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/QUICK_REFERENCE.md

Paso 3: Verificar estado del proyecto

cd /mnt/cello2/arno/re/recode/zig/zcatui
git status
git log --oneline -3
zig build test

Paso 4: Continuar trabajo

Una vez verificado el estado, continúa desde donde se dejó o atiende la solicitud del usuario.

Sobre TEAM_STANDARDS

Es el repositorio centralizado con todas las normas de trabajo del equipo:

• LAST_UPDATE.md - Cambios recientes (leer siempre primero)
• NORMAS_TRABAJO_CONSENSUADAS.md - Metodología fundamental
• QUICK_REFERENCE.md - Cheat sheet rápido
• INFRASTRUCTURE/ - Documentación de servidores, Zig 0.15 guía
• PROJECTS/ - Estado de todos los proyectos

---

INFORMACIÓN DEL PROYECTO

Nombre: zcatui Versión: v2.1 - FEATURE COMPLETE + INNOVATIONS Última actualización: 2025-12-08 Lenguaje: Zig 0.15.2 Inspiración: ratatui + crossterm (Rust) Estado: Librería completa y lista para producción

Descripción

zcatui es una librería TUI completa para Zig, equivalente a ratatui+crossterm de Rust pero en un solo paquete. Permite crear interfaces de usuario en terminal con widgets, eventos, animaciones, themes, y más.

Estadísticas

Métrica	Valor
Archivos fuente	67 archivos .zig
Widgets	34 widgets
Módulos core	20 módulos
Tests	250+ tests
Examples	11 demos ejecutables

Funcionalidades Principales

• ✅ Renderizado immediate-mode con double buffering y diff
• ✅ 34 widgets (más que ratatui)
• ✅ Sistema de eventos teclado/ratón
• ✅ Sistema de animaciones con easing
• ✅ Clipboard (OSC 52)
• ✅ Hyperlinks (OSC 8)
• ✅ Imágenes en terminal (Kitty/iTerm2)
• ✅ Notificaciones desktop (OSC 9/777)
• ✅ Focus management global
• ✅ Sistema de themes con hot-reload
• ✅ Unicode width calculation (wcwidth)
• ✅ Terminal capability detection
• ✅ Lazy rendering con cache

Nuevos en v2.1

• ✅ Spinner - Indicadores de carga animados (17 estilos)
• ✅ Help - Auto-genera ayuda de keybindings
• ✅ Viewport - Scroll genérico con buffer interno
• ✅ Progress - Barras de progreso con ETA y velocidad
• ✅ Markdown - Renderizado de Markdown styled
• ✅ DirectoryTree - Navegador de archivos
• ✅ SyntaxHighlighter - Resaltado de sintaxis (10 lenguajes)
• ✅ Flex Layout - CSS-like justify/align
• ✅ Widget Testing Framework - Harness, assertions, benchmarks
• ✅ Theme Hot-Reload - Cargar themes desde archivos JSON/KV
• ✅ Widget Serialization - JSON export, undo/redo, snapshots
• ✅ Accessibility - Roles ARIA, announcements, high contrast

---

RUTAS IMPORTANTES

# Este proyecto
/mnt/cello2/arno/re/recode/zig/zcatui/

# Normas del equipo (LEER SIEMPRE)
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/

# Compilador Zig 0.15.2
/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig

# Guía Zig 0.15 (cambios de API)
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/INFRASTRUCTURE/ZIG_0.15_GUIA.md

---

COMANDOS FRECUENTES

# Compilar
zig build

# Tests (186+ tests)
zig build test

# Ejecutar ejemplos
zig build hello
zig build events-demo
zig build list-demo
zig build table-demo
zig build dashboard
zig build input-demo
zig build animation-demo
zig build clipboard-demo
zig build menu-demo
zig build form-demo
zig build panel-demo

# Git
git status
git add -A && git commit -m "mensaje"
git push

---

ESTRUCTURA DEL PROYECTO

zcatui/
├── src/
│   ├── root.zig              # Entry point, re-exports
│   │
│   ├── ─── CORE ───
│   ├── buffer.zig            # Buffer, Cell, Rect, Symbol
│   ├── style.zig             # Color, Style, Modifier
│   ├── text.zig              # Text, Line, Span
│   ├── layout.zig            # Layout, Constraint
│   ├── terminal.zig          # Terminal abstraction
│   │
│   ├── ─── EVENTOS ───
│   ├── event.zig             # Event, KeyEvent, MouseEvent
│   ├── event/
│   │   ├── reader.zig        # EventReader
│   │   └── parse.zig         # Escape parser
│   │
│   ├── ─── FEATURES ───
│   ├── focus.zig             # FocusRing, FocusManager
│   ├── theme.zig             # 10 themes predefinidos
│   ├── animation.zig         # Easing, Timer
│   ├── cursor.zig            # Cursor control
│   ├── clipboard.zig         # OSC 52
│   ├── hyperlink.zig         # OSC 8
│   ├── notification.zig      # OSC 9/777
│   ├── image.zig             # Kitty/iTerm2
│   ├── lazy.zig              # RenderCache, Throttle
│   ├── unicode.zig           # charWidth, stringWidth
│   ├── termcap.zig           # Terminal detection
│   │
│   ├── ─── BACKEND ───
│   ├── backend/
│   │   └── backend.zig       # ANSI sequences
│   │
│   ├── ─── SYMBOLS ───
│   ├── symbols/              # line, border, block, bar, braille...
│   │
│   ├── ─── WIDGETS (34) ───
│   ├── widgets/
│   │   ├── block.zig         # Block (borders, titles)
│   │   ├── paragraph.zig     # Text wrapping
│   │   ├── list.zig          # Selectable list
│   │   ├── table.zig         # Multi-column table
│   │   ├── gauge.zig         # Progress bars
│   │   ├── tabs.zig          # Tab navigation
│   │   ├── sparkline.zig     # Mini graphs
│   │   ├── scrollbar.zig     # Scroll indicator
│   │   ├── barchart.zig      # Bar charts
│   │   ├── canvas.zig        # Drawing
│   │   ├── chart.zig         # Graphs with axes
│   │   ├── calendar.zig      # Monthly calendar
│   │   ├── clear.zig         # Clear area
│   │   ├── input.zig         # Text input
│   │   ├── textarea.zig      # Multi-line editor
│   │   ├── popup.zig         # Popup + Modal
│   │   ├── menu.zig          # Menu, MenuBar, ContextMenu
│   │   ├── tooltip.zig       # Tooltips
│   │   ├── tree.zig          # Tree view
│   │   ├── filepicker.zig    # File picker
│   │   ├── scroll.zig        # ScrollView, VirtualList
│   │   ├── panel.zig         # Panel, TabbedPanel
│   │   ├── checkbox.zig      # Checkbox, RadioGroup
│   │   ├── select.zig        # Select dropdown
│   │   ├── slider.zig        # Slider
│   │   ├── statusbar.zig     # StatusBar, Toast
│   │   ├── spinner.zig       # Spinner (17 estilos) [NEW v2.1]
│   │   ├── help.zig          # Help (auto keybindings) [NEW v2.1]
│   │   ├── viewport.zig      # Viewport (scroll genérico) [NEW v2.1]
│   │   ├── progress.zig      # Progress (ETA, speed) [NEW v2.1]
│   │   ├── markdown.zig      # Markdown renderer [NEW v2.1]
│   │   ├── dirtree.zig       # DirectoryTree [NEW v2.1]
│   │   └── syntax.zig        # SyntaxHighlighter [NEW v2.1]
│   │
│   └── ─── TESTS ───
│   └── tests/                # Test suite
│
├── examples/                 # 11 demos
├── docs/                     # ARCHITECTURE.md, WIDGETS.md, API.md
├── build.zig
├── README.md
└── CLAUDE.md                 # Este archivo

---

NOTAS TÉCNICAS ZIG 0.15.2

Cambios de API importantes

// Campos de Style
style.foreground  // NO style.fg
style.background  // NO style.bg

// Sleep
std.Thread.sleep(ns)  // NO std.time.sleep

// Cell
cell.symbol  // NO cell.char

// Modifiers
style.add_modifier(.{ .bold = true })  // NO addModifier

Patrones comunes

// Builder pattern
pub fn setOption(self: Widget, value: T) Widget {
    var w = self;
    w.option = value;
    return w;
}

// Render pattern
pub fn render(self: Widget, area: Rect, buf: *Buffer) void {
    if (area.isEmpty()) return;
    // ...
}

// Focus interface (vtable)
pub const Focusable = struct {
    ptr: *anyopaque,
    vtable: *const VTable,
};

---

EQUIPO Y METODOLOGÍA

Quiénes Somos

• Usuario (Arno): Desarrollador independiente
• Claude: Asistente de programación (Claude Code / Opus 4.5)

Cómo Trabajamos

• Desarrollo iterativo con commits frecuentes
• Tests antes de features nuevas
• Documentación inline con /// doc comments
• Código idiomático Zig (snake_case, error handling explícito)
• Sin dependencias externas
• Commits descriptivos con emoji 🤖

Reglas Importantes

1. Siempre leer TEAM_STANDARDS/LAST_UPDATE.md al inicio
2. Verificar zig build test antes de commit
3. No ejecutar binarios/servidores que queden como zombies
4. Commits solo cuando el usuario lo pida

---

OTROS PROYECTOS ZIG

Proyecto	Descripción	Path
zcatui	TUI library (este)	/mnt/cello2/arno/re/recode/zig/zcatui
service-monitor	Monitor HTTP/TCP	/mnt/cello2/arno/re/recode/zig/service-monitor
zsqlite	SQLite wrapper	/mnt/cello2/arno/re/recode/zig/zsqlite
zpdf	PDF generator	/mnt/cello2/arno/re/recode/zig/zpdf

---

REPOSITORIOS

# Este proyecto
git@git.reugenio.com:reugenio/zcatui.git

# TEAM_STANDARDS
git@git.reugenio.com:reugenio/development-standards.git

# Servidor Git
git.reugenio.com (Forgejo)

---

HISTORIAL RECIENTE

Versión	Fecha	Cambios
v2.1	2025-12-08	7 nuevos widgets, Flex Layout, Testing Framework, Theme Hot-Reload, Serialization, Accessibility, 250+ tests
v2.0	2025-12-08	Focus, themes, unicode, termcap, 186+ tests
v1.4	2025-12-08	Form widgets, panels, scroll, tree
v1.3	2025-12-08	Menus, modals, animation, clipboard
v1.2	2025-12-08	Sistema eventos
v1.0	2025-12-08	13 widgets iniciales

---

ESTADO ACTUAL

El proyecto está FEATURE COMPLETE + INNOVATIONS (v2.1)

• ✅ 34 widgets implementados (7 nuevos en v2.1)
• ✅ Todos los tests pasando (250+)
• ✅ Manual técnico completo (docs/TECHNICAL_REFERENCE.md)
• ✅ Examples funcionando
• ✅ Flex Layout CSS-like
• ✅ Testing Framework para widgets
• ✅ Theme hot-reload desde archivos
• ✅ Widget serialization (JSON, undo/redo)
• ✅ Accessibility básico (ARIA roles, announcements)

Posibles mejoras futuras (opcionales):

• Performance: SIMD para buffer
• Más examples específicos de v2.1 widgets
• Tutorial paso a paso
• Publicación en package registry

---

REFERENCIAS

• ratatui (Rust): https://ratatui.rs/
• Zig docs 0.15: https://ziglang.org/documentation/0.15.0/std/
• ANSI codes: https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797