zcatgui/CLAUDE.md

zcatgui - GUI 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

git status && git log --oneline -5
zig build test

Nota: Usamos git con commits frecuentes. Ver teamdocs/NORMAS_ESENCIALES.md sección VCS.

Paso 3: Leer documentación del proyecto

REFERENCE.md                                      # ⭐ MANUAL DE REFERENCIA COMPLETO
CHANGELOG.md                                      # Historial de versiones
docs/DEVELOPMENT_PLAN.md                          # Plan de desarrollo por fases
docs/ARCHITECTURE.md                              # Arquitectura y decisiones de diseño
docs/MOBILE_WEB_BACKENDS.md                       # Documentación backends mobile/web
docs/research/DVUI_AUDIT_2025-12-17.md           # Auditoría DVUI (paridad visual)
docs/research/WIDGET_COMPARISON.md                # Comparativa zcatgui vs DVUI vs Gio

Paso 4: Verificar estado del proyecto

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

Paso 5: Continuar trabajo

Una vez verificado el estado, continúa desde donde se dejó.

---

REGLA CRÍTICA: NO EJECUTAR BINARIOS GUI

NUNCA ejecutar programas GUI directamente con ./programa o en background

Los procesos GUI no terminan correctamente desde Claude Code y dejan shells zombie que:

1. Consumen contexto de la conversación con mensajes "Background Bash running"
2. Fuerzan compactaciones prematuras del contexto
3. Degradan severamente la calidad de la sesión de trabajo

Alternativas:

• Para verificar que compila: zig build (sin ejecutar)
• Para probar muy brevemente: timeout 2s ./programa 2>&1 || true
• Mejor opción: Pedir al usuario que lo pruebe y reporte

Esta regla está documentada en teamdocs desde 2025-11-30.

---

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

---

DOCUMENTACIÓN EN TEAMDOCS

Al documentar trabajo en teamdocs/agenda/:

1. Entrada en agenda: Máximo 5 líneas (QUÉ + CUÁNDO + link)
2. Detalle técnico: Crear hito en agenda/hitos/
3. Protocolo completo: Ver teamdocs/ESTRUCTURA_DOCUMENTACION.md

Formato de entrada:

## Fecha - Título ✅

Resumen breve (1-2 frases). Resultado principal.

→ [Detalle técnico](hitos/YYYY-MM-DD_tema.md)

---

INFORMACIÓN DEL PROYECTO

Campo	Valor
Nombre	zcatgui
Versión	v0.21.2
Fecha inicio	2025-12-09
Estado	✅ COMPLETO - 37 widgets, ~35K LOC, 4 backends, TTF funcional
Lenguaje	Zig 0.15.2
Paradigma	Immediate Mode GUI
Inspiración	Gio (Go), microui (C), DVUI (Zig), Dear ImGui (C++)

Descripción

zcatgui es una librería GUI immediate-mode para Zig:

1. Software Rendering por defecto - Funciona en cualquier ordenador sin GPU
2. Cross-platform - Linux, Windows, macOS, Web (WASM), Android, iOS
3. SSH compatible - Funciona via X11 forwarding
4. Sistema de Macros - Grabación/reproducción de acciones
5. Sin dependencias pesadas - Solo SDL2 para desktop

Filosofía

"Máxima compatibilidad, mínimas dependencias, control total del usuario"

---

RUTAS IMPORTANTES

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

# Proyecto hermano (TUI)
/mnt/cello2/arno/re/recode/zig/zcatui/

# Proyecto de referencia (Fyne/Go)
/mnt/cello2/arno/re/recode/go/simifactu/

# Normas del equipo
/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

---

COMANDOS FRECUENTES

# Compilar (desktop)
zig build

# Tests
zig build test

# Ejemplos desktop
zig build hello
zig build widgets-demo
zig build table-demo

# WASM (navegador)
zig build wasm                    # Genera web/zcatgui-demo.wasm
cd web && python3 -m http.server  # Servir en localhost:8000

# Android (requiere NDK)
zig build android                 # ARM64 para dispositivo

# iOS (requiere macOS + Xcode)
zig build ios                     # ARM64 para dispositivo

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

---

ARQUITECTURA

Paradigma: Immediate Mode

┌─────────────────────────────────────────────────────────────┐
│  while (running) {                                          │
│      events = pollEvents();     // Input                    │
│      updateState(events);       // TÚ manejas estado        │
│      commands = drawUI(state);  // Genera comandos          │
│      render(commands);          // Dibuja                   │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘

Capas de la Librería

┌─────────────────────────────────────────────────────────────┐
│  Capa 4: Widgets (Table, Panel, Select, Modal, etc.)        │
├─────────────────────────────────────────────────────────────┤
│  Capa 3: Sistema de Macros                                  │
├─────────────────────────────────────────────────────────────┤
│  Capa 2: Core UI (Context, Layout, Style, Input, Commands)  │
├─────────────────────────────────────────────────────────────┤
│  Capa 1: Rendering (Software Rasterizer, Framebuffer, Fonts)│
├─────────────────────────────────────────────────────────────┤
│  Capa 0: Backend (SDL2 - ventanas, eventos, display)        │
└─────────────────────────────────────────────────────────────┘

→ Detalle completo: docs/ARCHITECTURE.md

---

ESTRUCTURA DE ARCHIVOS

zcatgui/
├── src/
│   ├── zcatgui.zig          # Entry point, re-exports
│   ├── core/                # Context, Layout, Style, Input, Command, etc.
│   ├── widgets/             # 37 widgets implementados
│   │   ├── autocomplete/    # Modular: state, types, filtering
│   │   ├── icon/            # Modular: types, drawing_helpers
│   │   ├── textarea/        # Modular: state, render, types
│   │   ├── progress/        # Modular: bar, circle, spinner
│   │   ├── table/           # Tabla simple
│   │   ├── advanced_table/  # Tabla avanzada con CRUD
│   │   ├── virtual_advanced_table/  # Tabla virtual con paginación
│   │   └── ...              # Widgets simples (archivos individuales)
│   ├── render/              # Software renderer, fonts, animation, effects
│   ├── backend/             # SDL2, WASM, Android, iOS
│   ├── macro/               # MacroRecorder, MacroPlayer
│   └── utils/               # FrameArena, ObjectPool, Benchmark
├── examples/                # Demos: hello, widgets, table, wasm, android
├── web/                     # WASM support
├── ios/                     # iOS bridge (Objective-C)
├── docs/                    # Documentación detallada
├── CLAUDE.md                # Este archivo
├── REFERENCE.md             # ⭐ Manual de referencia completo
└── CHANGELOG.md             # Historial de versiones

---

ESTADO ACTUAL (v0.25.0)

Widgets (38 total)

Categoría	Widgets
Básicos	Label, Button, Checkbox, Radio, Slider, TextInput, NumberEntry
Contenedores	Panel, Split, Modal, Scroll, Tabs, Menu
Datos	List, Table, Tree, ReorderableList, VirtualScroll
Feedback	Progress, Tooltip, Toast, Spinner
Input avanzado	AutoComplete, Select, TextArea, ColorPicker, DatePicker
Especial	Image, Icon, Canvas, Chart, RichText, IdleCompanion
Navegación	Breadcrumb, Focus, Badge/TagGroup

Backends (5 plataformas)

• SDL2: Desktop (Linux, Windows, macOS)
• WASM: Navegadores web (Canvas 2D)
• Android: ANativeActivity + ANativeWindow
• iOS: UIKit bridge (Objective-C)

Core Systems

• Context (FrameArena, dirty rectangles, ID system)
• Input (keyboard, mouse, touch, shortcuts, gestures)
• Rendering (software renderer, AA, effects)
• Animation (20+ easing functions, springs)
• Themes (dark, light, high_contrast, nord, dracula)

Métricas

• ~35,000 LOC en 81 archivos fuente
• 0 warnings, 0 memory leaks
• WASM: ~18KB compilado

→ Detalle completo: REFERENCE.md

---

HITOS RECIENTES

Liquid UI V2 ✅ (2025-12-30)

Sistema de transiciones de color suaves para paneles:

• ColorTransition: 500ms (medio segundo) para transiciones perceptibles
• Mayor contraste: Dark mode 4%/20% base, Light mode 1%/6% base
• requestAnimationFrame(): Paneles solicitan redraw durante animación
• Fondo de paneles "fluye" al cambiar focus → Archivos: render/animation.zig, core/style.zig, core/context.zig

IdleCompanion Widget ✅ (2025-12-30)

Mascota animada que aparece tras inactividad del usuario:

• Se asoma por bordes de paneles aleatorios
• Ojos que miran a los lados, orejas con movimiento
• Salto de pánico al detectar actividad
• Clipping correcto (respeta límites del panel) → Archivo: widgets/idle_companion.zig

Primitivas Gráficas 2D ✅ (2025-12-30)

Nuevas primitivas para formas orgánicas:

• FilledTriangle: Rasterización por scanlines (v0.23.0)
• FilledCircle: Algoritmo Midpoint/Bresenham (v0.24.0) → Archivos: core/command.zig, render/software.zig

Refactorización Modular ✅ (2025-12-29)

Archivos grandes modularizados en carpetas:

• autocomplete/ (910→571 LOC hub, -37%): state, types, filtering
• icon/ (805→515 LOC hub, -36%): types, drawing_helpers → Detalle: docs/REFACTORING_MODULAR_2025-12-29.md

AdvancedTable Color por Focus ✅ (2025-12-19)

Fila seleccionada cambia color según focus de la tabla:

• selected_row: color con focus (accent)
• selected_row_unfocus: color sin focus (gris sutil)
• BasicColors acepta override desde aplicación

TTF Rendering ✅ (2025-12-17)

Integración zcatttf v1.0 - texto TTF funciona perfectamente. → Librería: /mnt/cello2/arno/re/recode/zig/zcatttf/

Paridad Visual DVUI ✅ (2025-12-17)

Sistema dual (simple/fancy), esquinas redondeadas, sombras, transiciones, focus ring AA. → Detalle: docs/research/DVUI_AUDIT_2025-12-17.md

AdvancedTable ✅ (2025-12-17)

Widget ~3,700 LOC con schema, CRUD, sorting, lookup, multi-select, search, validation. → Detalle: docs/ADVANCED_TABLE_MERGE_PLAN.md

---

SISTEMA DE MACROS

Grabar y reproducir acciones del usuario con teclas raw (como Vim).

pub const MacroRecorder = struct {
    pub fn start(self: *MacroRecorder) void;
    pub fn stop(self: *MacroRecorder) []const KeyEvent;
    pub fn record(self: *MacroRecorder, key: KeyEvent) void;
};

pub const MacroPlayer = struct {
    pub fn play(events: []const KeyEvent, inject_fn: fn(KeyEvent) void) void;
};

→ Detalle: src/macro/macro.zig

---

DECISIONES DE DISEÑO

Decisión	Razón
Immediate Mode	Control total, sin threading hell, estado explícito
Software Rendering	Máxima compatibilidad (SSH, HP viejo, cualquier driver)
Macros con teclas raw	Simple como Vim, menos código = menos bugs
SDL2 backend	Cross-platform probado, fácil de usar
Bitmap + TTF fonts	Bitmap siempre funciona, TTF para flexibilidad

→ Detalle: docs/ARCHITECTURE.md

---

OPTIMIZACIONES DE RENDIMIENTO (2026-01-03)

Optimizaciones Activas ✅

Optimización	Archivo	Descripción
Turbo Píxeles	render/framebuffer.zig:117	@setRuntimeSafety(false) en fillRect - elimina bounds checks en hot path
Fast Path Texto	render/ttf.zig:323,375	Escritura directa para píxeles opacos (alpha==255), evita blend innecesario

Optimización Probada y Revertida ❌

Optimización	Problema	Alternativa
Burst Suppression (auto-gestión de estrés)	Causaba paneles vacíos durante navegación rápida	El debounce en DataManager ya evita queries excesivas

Detalles del Burst Suppression:

• Concepto: suprimir dibujo de paneles durante ráfagas de navegación (<100ms)
• Implementación: if (!frame_result.should_draw) return; en paneles
• Problema: el frame se dibujaba vacío (solo fondo), sin widgets
• Causa raíz: suprimía TODO el dibujo, no solo las queries BD
• Lección: el debounce a nivel DataManager es más elegante

Pendiente verificar: Mensajes continuos de redraw en idle (posible bug en animaciones).

---

NOTAS ZIG 0.15.2

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

// ArrayList - CAMBIÓ en 0.15
var list: std.ArrayListUnmanaged(T) = .{};
defer list.deinit(allocator);
try list.append(allocator, item);  // allocator en cada operación

// stdout
const stdout = std.fs.File.stdout();  // NO std.io.getStdOut()

// build.zig.zon
.{
    .fingerprint = 0x...,
    .name = .proyecto,  // enum literal, no string
}

---

PROYECTOS RELACIONADOS

Proyecto	Ruta	Descripción
zcatttf	/mnt/cello2/arno/re/recode/zig/zcatttf/	Librería TTF v1.0 (dependencia)
zsimifactu	/mnt/cello2/arno/re/recode/zig/zsimifactu/	App facturación (consumidor principal)
zcatui	/mnt/cello2/arno/re/recode/zig/zcatui/	TUI library (hermano)
zcatp2p	/mnt/cello2/arno/re/recode/zig/zcatp2p/	Librería P2P v1.0.0
simifactu	/mnt/cello2/arno/re/recode/go/simifactu/	App referencia (Fyne/Go)

---

EQUIPO

• Usuario (R.Eugenio): Desarrollador principal
• Claude: Asistente de programación (Claude Code / Opus 4.5)

---

REFERENCIAS EXTERNAS

• microui - Arquitectura mínima
• DVUI - Zig GUI reference
• Gio - Go immediate-mode
• Dear ImGui - C++ reference