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
```bash
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.0 - FEATURE COMPLETE
**Última actualización:** 2025-12-08
**Lenguaje:** Zig 0.15.2
**Inspiración:** [ratatui](https://github.com/ratatui/ratatui) + [crossterm](https://github.com/crossterm-rs/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 | 60 archivos .zig |
| Widgets | 27 widgets |
| Módulos core | 16 módulos |
| Tests | 186+ tests |
| Examples | 11 demos ejecutables |

### Funcionalidades Principales
- ✅ Renderizado immediate-mode con double buffering y diff
- ✅ 27 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 (10 themes predefinidos)
- ✅ Unicode width calculation (wcwidth)
- ✅ Terminal capability detection
- ✅ Lazy rendering con cache

---

## 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

```bash
# 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 (27) ───
│   ├── 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
│   │
│   └── ─── 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
```zig
// 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
```zig
// 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

```bash
# 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.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 (v2.0)**

- ✅ Todos los widgets implementados
- ✅ Todos los tests pasando (186+)
- ✅ Documentación completa
- ✅ Examples funcionando

**Posibles mejoras futuras (opcionales):**
- Performance: SIMD para buffer
- Más examples específicos
- 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