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/teamdocs/NORMAS_ESENCIALES.md
```
Contiene: rutas, VCS (git), flujo de trabajo, credenciales.

### Paso 2: Verificar estado con git
```bash
git status && git log --oneline -5
zig build test
```
**Nota:** Usamos git con commits frecuentes. Ver `teamdocs/NORMAS_ESENCIALES.md` sección VCS.

### Paso 4: Continuar trabajo
Una vez verificado el estado, continúa desde donde se dejó o atiende la solicitud del usuario.

### Sobre teamdocs
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.2 - 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 | 70+ archivos .zig |
| Widgets | 35 widgets |
| Módulos core | 30+ módulos |
| Tests | **281 tests** |
| Examples | 20 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.2
- ✅ **ResizeHandler** - Detección SIGWINCH de redimensión de terminal
- ✅ **DragState/Splitter** - Mouse drag & drop, paneles redimensionables
- ✅ **Diagnostic** - Mensajes de error estilo Elm con snippets
- ✅ **DebugOverlay** - Overlay de debug (FPS, timing, widgets)
- ✅ **Profiler** - Profiling de rendimiento con timers
- ✅ **SixelEncoder** - Codificación Sixel para imágenes
- ✅ **AsyncLoop** - Event loop async con epoll y timers
- ✅ **Compose** - Utilidades de composición de widgets
- ✅ **Shortcuts** - Registro de atajos de teclado
- ✅ **Logo** - Widget de logo ASCII art
- ✅ **Layout.ratio()** - Constraint proporcional
- ✅ **build.zig.zon** - Soporte package manager

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

# 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/teamdocs/INFRASTRUCTURE/ZIG_0.15_GUIA.md
```

---

## COMANDOS FRECUENTES

```bash
# Compilar
zig build

# Tests (186+ tests)
zig build test

# Ejecutar ejemplos (20 demos)
zig build hello           # Hello World básico
zig build events-demo     # Manejo de eventos
zig build list-demo       # Lista interactiva
zig build table-demo      # Tabla con datos
zig build dashboard       # Dashboard completo
zig build input-demo      # Campos de entrada
zig build animation-demo  # Animaciones
zig build clipboard-demo  # Clipboard
zig build menu-demo       # Menús
zig build form-demo       # Formularios
zig build panel-demo      # Paneles
zig build resize-demo     # Manejo resize [v2.2]
zig build splitter-demo   # Paneles redimensionables [v2.2]
zig build dirtree-demo    # Navegador archivos [v2.1]
zig build spinner-demo    # Spinners [v2.1]
zig build progress-demo   # Barras progreso [v2.1]
zig build markdown-demo   # Markdown [v2.1]
zig build syntax-demo     # Syntax highlighting [v2.1]
zig build help-demo       # Panel de ayuda [v2.1]
zig build viewport-demo   # Scroll viewport [v2.1]

# 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]
│   │   └── logo.zig          # Logo ASCII art [NEW v2.2]
│   │
│   ├── ─── V2.2 MODULES ───
│   ├── resize.zig            # SIGWINCH resize detection [NEW v2.2]
│   ├── drag.zig              # DragState, Splitter [NEW v2.2]
│   ├── diagnostic.zig        # Elm-style errors [NEW v2.2]
│   ├── debug.zig             # Debug overlay [NEW v2.2]
│   ├── profile.zig           # Performance profiler [NEW v2.2]
│   ├── sixel.zig             # Sixel encoding [NEW v2.2]
│   ├── async_loop.zig        # Async epoll loop [NEW v2.2]
│   ├── compose.zig           # Widget composition [NEW v2.2]
│   └── shortcuts.zig         # Shortcut registry [NEW v2.2]
│   │
│   └── ─── TESTS ───
│   └── tests/                # Test suite
│
├── examples/                 # 20 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 teamdocs/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

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

# Servidor Git
git.reugenio.com (Forgejo)
```

---

## HISTORIAL RECIENTE

| Versión | Fecha | Cambios |
|---------|-------|---------|
| v2.2 | 2025-12-08 | 13 módulos nuevos: resize, drag, diagnostic, debug, profile, sixel, async_loop, compose, shortcuts, logo, build.zig.zon |
| v2.1 | 2025-12-08 | 7 nuevos widgets, Flex Layout, Testing Framework, Theme Hot-Reload, Serialization, Accessibility |
| 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.2)**

- ✅ 35 widgets implementados
- ✅ 30+ módulos core
- ✅ Todos los tests pasando (186+)
- ✅ 20 demos ejecutables
- ✅ Documentación completa
- ✅ build.zig.zon para package manager

**Nuevas capacidades en v2.2:**
- ✅ Terminal resize detection (SIGWINCH)
- ✅ Mouse drag & drop, splitter panels
- ✅ Elm-style diagnostic messages
- ✅ Debug overlay (FPS, timing)
- ✅ Performance profiling
- ✅ Sixel graphics encoding
- ✅ Async event loop (epoll)

**Posibles mejoras futuras (opcionales):**
- Performance: SIMD para buffer
- Tutorial paso a paso
- Publicación en Zig package registry

---

## DOCUMENTACIÓN

| Documento | Ubicación | Descripción |
|-----------|-----------|-------------|
| **API_REFERENCE.md** | `docs/API_REFERENCE.md` | Manual completo de referencia (1400 líneas) - LEER PARA USAR LA LIBRERÍA |
| ARCHITECTURE.md | `docs/ARCHITECTURE.md` | Arquitectura técnica |
| WIDGETS.md | `docs/WIDGETS.md` | Guía de widgets |
| PLAN_V2.2.md | `docs/PLAN_V2.2.md` | Plan de implementación v2.2 |

### Paradigma de la Librería

**zcatui es Immediate Mode** (como ratatui, Dear ImGui, egui):
- No hay árbol de widgets persistente
- Cada frame describes toda la UI desde cero
- El estado lo maneja el usuario, no la librería
- Flujo: `Estado → render() → Buffer → diff() → Terminal → pollEvent() → Estado`

```zig
// Patrón típico
while (running) {
    try term.draw(render);  // Redibuja TODO cada frame
    if (try term.pollEvent(16)) |event| {
        updateState(event);  // TÚ manejas el estado
    }
}
fn render(area: Rect, buf: *Buffer) void {
    // UI es función pura de tu estado
    widget.render(area, buf);
}
```

---

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

---

## RESUMEN PARA NUEVA CONVERSACIÓN

Si eres una nueva instancia de Claude, esto es lo que necesitas saber:

1. **Qué es**: Librería TUI para Zig, equivalente a ratatui+crossterm de Rust
2. **Estado**: v2.2 COMPLETA - 70+ archivos, 35 widgets, 186+ tests, 20 demos
3. **Paradigma**: Immediate Mode (sin árbol de widgets, estado externo)
4. **Leer primero**:
   - `teamdocs/LAST_UPDATE.md` (normas actualizadas)
   - `docs/API_REFERENCE.md` (referencia completa de la API)
5. **Compilador**: `/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig`
6. **Verificar**: `zig build test` antes de cualquier commit
7. **Commits**: Solo cuando el usuario lo pida, con formato estándar

### Comandos de verificación rápida:
```bash
cd /mnt/cello2/arno/re/recode/zig/zcatui
git status && git log --oneline -3
zig build test
```

---

## CLAUDE CODE + ZLS (LSP)

Claude Code tiene integración LSP con zls (Zig Language Server).

**Plugin:** `$HOME/.claude/plugins/zls-lsp/`

**Operaciones disponibles:**

| Operación | Uso |
|-----------|-----|
| `goToDefinition` | Navegar a definición de símbolo |
| `findReferences` | Encontrar todas las referencias |
| `hover` | Info de tipo y documentación |
| `documentSymbol` | Símbolos del archivo actual |
| `incomingCalls` | Qué funciones llaman a ésta |

**Documentación:** `teamdocs/INFRASTRUCTURE/ZLS_LSP_CLAUDE_CODE.md`