zcatgui/docs/research/DVUI_AUDIT_2025-12-17.md

Auditoría Completa: DVUI vs zcatgui

Fecha: 2025-12-17 Objetivo: Identificar TODAS las características de DVUI que faltan en zcatgui Versiones: DVUI main (Dec 2025) | zcatgui v0.16.2

---

1. RESUMEN EJECUTIVO

Estado Actual

Aspecto	zcatgui	DVUI	Gap
Widgets	~45	~42	✅ Paridad
Rendering Visual	Básico	Avanzado	❌ CRÍTICO
Anti-aliasing	Supersampling TTF	Edge-fade triangles	⚠️ Diferente
Esquinas redondeadas	❌ No	✅ Sí	❌ FALTA
Sombras	✅ API existe	✅ Box shadow	⚠️ No usado
Backends	4 (SDL2,WASM,Android,iOS)	6 (SDL2/3,Raylib,DX11,Web)	✅ OK
Themes	5	6	✅ OK

Conclusión Principal

El gap NO está en cantidad de widgets, sino en CALIDAD VISUAL del rendering.

DVUI se ve mejor porque:

1. Usa triangulación con anti-aliasing en bordes (fade to transparent)
2. Tiene esquinas redondeadas nativas en todos los widgets
3. Aplica ninepatch para efectos visuales complejos
4. Estados visuales pulidos (hover, press, focus)

---

2. ANÁLISIS DEL SISTEMA DE RENDERING DE DVUI

2.1 Arquitectura de Rendering

DVUI usa un enfoque de triangulación con vértices:

Widget → Path (arcs, lines) → Triangles → GPU/CPU render

Características clave:

• Todos los elementos se convierten en triángulos
• Anti-aliasing via 2 vértices por borde: inner (opaco) + outer (transparente)
• Tamaño de AA fijo: 1 pixel
• Soporte para GPU (DirectX, SDL3GPU) y CPU fallback

2.2 Path Drawing

// DVUI: Esquinas redondeadas con arcos
pub fn addRect(corner_radii) {
    // 4 arcos (uno por esquina)
    // 4 líneas conectando arcos
    // Triangulación automática
}

// Error de discretización configurable
theta = acos(radius / (radius + 0.5)); // 0.5px error máximo

2.3 Anti-Aliasing

DVUI usa "edge fade":

• Cada borde tiene 2 vértices paralelos
• Vértice interno: color sólido (alpha = 1.0)
• Vértice externo: transparente (alpha = 0.0)
• Interpolación lineal entre ambos crea suavizado

Ventajas:

• Funciona con GPU (hardware interpolation)
• Funciona con CPU (software interpolation)
• No requiere multisampling

2.4 Fill Modes

1. Convex Fill: Para polígonos convexos simples

   • Triangulación desde centro
   • Opcional: fade en bordes

2. Stroke Fill: Para líneas y bordes

   • Extrusión de geometría
   • Miter joints con límite de ángulo
   • AA fringe de 1px

---

3. INVENTARIO COMPLETO DE WIDGETS

3.1 DVUI Widgets (42 archivos)

Categoría	Widgets
Layout	BoxWidget, FlexBoxWidget, GridWidget, PanedWidget, ScrollContainerWidget, OverlayWidget
Input	TextEntryWidget, ButtonWidget, DropdownWidget, ColorPickerWidget, ScaleWidget
Display	LabelWidget, IconWidget, PlotWidget, TextLayoutWidget
Navigation	MenuWidget, MenuItemWidget, TabsWidget, TreeWidget
Floating	FloatingWidget, FloatingWindowWidget, FloatingMenuWidget, FloatingTooltipWidget
Utility	AnimateWidget, CacheWidget, ContextWidget, FocusGroupWidget, ReorderWidget, ScrollAreaWidget, ScrollBarWidget, SuggestionWidget, VirtualParentWidget

3.2 zcatgui Widgets (~45 archivos)

Categoría	Widgets
Básicos	label, button, checkbox, radio, slider, text_input, numberentry
Layout	panel, split, modal, scroll, tabs, menu, grid
Datos	list, table, tree, reorderable, virtual_scroll
Feedback	progress, tooltip, toast, loader
Input Avanzado	autocomplete, select, textarea, colorpicker, datepicker
Especial	image, icon, canvas, chart, richtext, breadcrumb, badge
Navegación	appbar, navdrawer, sheet, divider, discloser
Extra	switch, surface, resize, selectable, iconbutton, focus

3.3 Comparación Widget por Widget

Widget	zcatgui	DVUI	Notas
Button	✅	✅	DVUI: esquinas redondeadas
Label	✅	✅	Similar
TextInput	✅	✅	DVUI: mejor touch
Checkbox	✅	✅	DVUI: animación
Radio	✅	✅	Similar
Slider	✅ ScaleWidget	✅	Similar
Select/Dropdown	✅	✅	Similar
Panel/Box	✅	✅	Similar
Split/Paned	✅	✅	Similar
Tabs	✅	✅	Similar
ScrollArea	✅	✅	DVUI: smooth scroll
Modal	✅	❌ FloatingWindow	Diferentes
Grid	✅	✅	Similar
Menu	✅	✅	Similar
Tree	✅	✅	Similar
Tooltip	✅	✅	Similar
Toast	✅	❌	zcatgui único
Progress	✅	❌	zcatgui único
ColorPicker	✅	✅	Similar
DatePicker	✅	❌	zcatgui único
Image	✅	✅	DVUI: stb_image
Icon	✅	✅ TinyVG	DVUI: vectorial
Chart/Plot	✅	✅	Similar
Canvas	✅	❌	zcatgui único
VirtualScroll	✅	✅	Similar
Reorderable	✅	✅	Similar
AppBar	✅	❌	zcatgui único
NavDrawer	✅	❌	zcatgui único
Breadcrumb	✅	❌	zcatgui único
Badge	✅	❌	zcatgui único
RichText	✅	✅ TextLayout	Similar
Loader/Spinner	✅	❌	zcatgui único
Switch	✅	❌	zcatgui único
Autocomplete	✅	✅ Suggestion	Similar
Table editable	✅⭐	❌ Grid básico	zcatgui superior
Floating Window	❌	✅	DVUI único
Animate	❌ directo	✅	DVUI: widget dedicado
Cache	❌	✅	DVUI: optimización

Conclusión Widgets: zcatgui tiene MÁS widgets que DVUI, incluyendo varios únicos.

---

4. DIFERENCIAS CRÍTICAS DE RENDERING

4.1 Lo que DVUI hace mejor visualmente

Aspecto	DVUI	zcatgui	Impacto Visual
Esquinas redondeadas	✅ corner_radius	❌ Solo rectángulos	⭐⭐⭐ ALTO
Anti-aliasing bordes	✅ Edge fade	❌ Solo en TTF	⭐⭐⭐ ALTO
Estados hover/press	✅ Transiciones suaves	⚠️ Cambio abrupto	⭐⭐ MEDIO
Focus ring	✅ 2px stroke suave	⚠️ Rectángulo	⭐⭐ MEDIO
Ninepatch	✅ Imágenes escalables	❌ No	⭐ BAJO
Box shadow	✅ Blur real	⚠️ API existe, no usada	⭐⭐ MEDIO

4.2 Lo que zcatgui hace igual o mejor

Aspecto	zcatgui	DVUI
TTF Rendering	✅ Supersampling 2x	✅ stb_truetype
Themes	✅ 5 themes	✅ 6 themes
Effects API	✅ Shadow, Gradient, Blur	⚠️ Solo shadow
Color utilities	✅ Básico	✅ HSLuv completo
Animation system	✅ 20+ easing functions	✅ Similar

---

5. SISTEMA DE THEMING

5.1 DVUI Themes

// DVUI: Theme estructura
Theme {
    // Colores por estilo
    styles: [content, control, window, highlight, err, app1, app2, app3]

    // Cada estilo tiene:
    fill, fill_hover, fill_press,
    text, text_hover, text_press,
    border,
    ninepatch_fill, ninepatch_hover, ninepatch_press,

    // Fuentes
    font_body, font_heading, font_title, font_mono,

    // Geometría
    max_default_corner_radius,

    // Meta
    dark: bool,
    focus_color,
    text_select_color,
}

5.2 Themes Disponibles

Theme	DVUI	zcatgui
Dark	✅	✅
Light	✅	✅
Adwaita	✅	❌
Dracula	✅	✅
Gruvbox	✅	❌
Jungle	✅	❌
OpenDyslexic	✅	❌
Win98	✅	❌
Solarized	❌	✅
High Contrast	❌	✅
Nord	❌	✅

---

6. FEATURES ADICIONALES DE DVUI

6.1 Features que NO tenemos

Feature	Descripción	Prioridad
structEntry	Auto-genera UI desde struct Zig	MEDIA
AccessKit	Soporte screen readers	BAJA
Fire-and-forget dialogs	Dialogs desde cualquier punto	MEDIA
HSLuv color space	Manipulación perceptual de colores	BAJA
TinyVG icons	Iconos vectoriales compactos	MEDIA
Ninepatch	Imágenes escalables 9-slice	BAJA
Cache Widget	Cacheo de rendering costoso	MEDIA
FPS throttling	Control de framerate	BAJA

6.2 Features que YA tenemos equivalentes

Feature	DVUI	zcatgui
Macro system	❌	✅ ÚNICO
Lego Panels	❌	✅ ÚNICO
DataManager	❌	✅ ÚNICO
Table editable	❌	✅ SUPERIOR
Progress widgets	❌	✅
Toast notifications	❌	✅
DatePicker	❌	✅
Multiple progress styles	❌	✅

---

7. EASING Y ANIMACIONES

7.1 DVUI Easing Functions

• Linear
• Quad (in/out/inOut)
• Cubic (in/out/inOut)
• Quart (in/out/inOut)
• Quint (in/out/inOut)
• Sine
• Exponential
• Circular
• Elastic
• Back
• Bounce

7.2 zcatgui Animation System

Ya tenemos en animation.zig:

• 20+ easing functions (similar a DVUI)
• AnimationManager
• Spring physics
• lerp/lerpInt utilities

Conclusión: Paridad en animaciones.

---

8. BACKENDS

8.1 Comparación

Backend	DVUI	zcatgui
SDL2	✅	✅
SDL3	✅	❌
SDL3GPU	✅	❌
Raylib	✅	❌
DirectX 11	✅	❌
Web/Canvas	✅	✅ WASM
Android	❌	✅
iOS	❌	✅

Conclusión: DVUI tiene más backends desktop, zcatgui tiene mobile.

---

9. GAP ANALYSIS - QUÉ IMPLEMENTAR

9.1 PRIORIDAD CRÍTICA (Mejora Visual Inmediata)

Mejora	Descripción	Esfuerzo	Impacto
Esquinas redondeadas	corner_radius en todos los widgets	ALTO	⭐⭐⭐
Anti-aliasing bordes	Edge-fade en rectángulos/líneas	ALTO	⭐⭐⭐
Aplicar sombras existentes	Usar Shadow API en widgets	MEDIO	⭐⭐
Hover/Press suave	Transición gradual de colores	MEDIO	⭐⭐

9.2 PRIORIDAD ALTA (Mejora UX)

Mejora	Descripción	Esfuerzo
Focus ring suave	Borde con AA en lugar de rectángulo
Smooth scrolling	Animación al hacer scroll
Button states	Hover → Press → Release animados
Color transitions	Animación entre estados de color

9.3 PRIORIDAD MEDIA (Features)

Feature	Descripción
structEntry	Auto UI desde structs
Cache widget	Para renders costosos
TinyVG icons	Iconos vectoriales
Más themes	Adwaita, Gruvbox, Win98

9.4 PRIORIDAD BAJA (Nice to have)

Feature	Descripción
AccessKit	Screen readers
HSLuv	Color perceptual
Ninepatch	9-slice images
SDL3 backend	Nuevo SDL

---

10. PLAN DE IMPLEMENTACIÓN PROPUESTO

Fase 1: Rendering Visual (CRÍTICO)

1. Implementar Path con esquinas redondeadas

   • Crear src/render/path.zig
   • Arcos discretizados
   • addRoundedRect()

2. Anti-aliasing en bordes

   • Modificar software.zig
   • Edge-fade technique
   • Aplicar a drawRect, drawLine

3. Actualizar widgets existentes

   • Button: corner_radius
   • Panel: corner_radius
   • TextInput: corner_radius
   • Select: corner_radius
   • Modal: corner_radius

Fase 2: Estados Visuales

4. Transiciones de estado

   • Integrar AnimationManager en widgets
   • Hover fade (200ms)
   • Press transition (100ms)

5. Focus ring mejorado

   • Borde con AA
   • Color de tema

Fase 3: Efectos

6. Aplicar sombras

   • Activar Shadow existente en Panel
   • Activar en Modal
   • Activar en Dropdown/Select

7. Mejorar gradientes

   • Usar en Progress bars
   • Opcional en buttons

Fase 4: Features Adicionales

8. Widget variants

   • button_simple vs button_fancy
   • panel_simple vs panel_fancy

9. Nuevos themes

   • Adwaita
   • Gruvbox

---

11. ARQUITECTURA PROPUESTA

11.1 Sistema Dual: Simple vs Fancy

// Configuración global
pub const RenderMode = enum {
    simple,  // Rápido, rectángulos, sin AA
    fancy,   // Esquinas redondeadas, AA, sombras
};

pub var render_mode: RenderMode = .fancy;

// En cada widget
pub fn button(ctx, text) {
    if (render_mode == .fancy) {
        drawRoundedRect(corner_radius: 5);
        applyShadow();
    } else {
        drawRect();
    }
}

11.2 Nuevos Módulos Necesarios

src/render/
├── path.zig          # NUEVO: Path con arcos y curvas
├── triangulate.zig   # NUEVO: Triangulación de paths
├── software.zig      # MODIFICAR: AA en primitivas
├── effects.zig       # YA EXISTE: Activar en widgets
├── antialiasing.zig  # YA EXISTE: Extender

---

12. MÉTRICAS DE ÉXITO

Antes vs Después

Aspecto	Antes	Después
Esquinas	Rectangulares	Redondeadas configurable
Bordes	Aliased	Anti-aliased
Sombras	No usadas	En paneles/modales
Transiciones	Abruptas	Suaves (200ms)
Focus	Rectángulo	Ring con AA

Comparación Visual Objetivo

ANTES (zcatgui actual):
┌────────────────┐
│   Botón        │  ← Esquinas 90°
└────────────────┘    Sin sombra
                      Cambio abrupto hover

DESPUÉS (estilo DVUI):
╭────────────────╮
│   Botón        │  ← Esquinas redondeadas
╰────────────────╯    Sombra sutil
                      Transición suave hover

---

13. CONCLUSIONES

Lo que DVUI hace mejor

1. Rendering visual - Esquinas redondeadas, AA en todo
2. Estados de widgets - Transiciones suaves
3. Consistencia visual - Todo se ve "pulido"

Lo que zcatgui hace mejor

1. Sistema de macros - Único
2. Table widget - Más completo (edit, sort, validate)
3. Lego Panels - Arquitectura de composición
4. Más widgets - Progress, DatePicker, Toast, etc.
5. Mobile backends - Android, iOS

Recomendación Final

NO necesitamos reescribir zcatgui. Necesitamos:

1. Añadir esquinas redondeadas (~500 LOC nuevo código)
2. Mejorar anti-aliasing (~300 LOC modificaciones)
3. Aplicar efectos existentes (~200 LOC en widgets)
4. Añadir transiciones (~400 LOC)

Total estimado: ~1,400 LOC para alcanzar paridad visual con DVUI.

El esfuerzo es significativamente menor que reescribir desde cero, y mantiene nuestras ventajas únicas (macros, table, panels).

---

Auditoría completada 2025-12-17