reugenio/zcatui
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
zcatui/CLAUDE.md

15 KiB
Raw Blame History

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 (jj), flujo de trabajo, credenciales.

Paso 2: Verificar estado con jj

jj status && jj log --limit 5
zig build test

Nota: Usamos jj (Jujutsu) en lugar de git. Ver teamdocs/INFRASTRUCTURE/JJ_JUJUTSU_VCS.md

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

# 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

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

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

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:

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