Documentacion actualizada para v1.1

- CLAUDE.md: actualizado a v1.1, seccion de optimizaciones
- docs/ARCHITECTURE.md: detalle de optimizaciones implementadas
- docs/API.md: nuevos tipos Symbol, DiffIterator, CellUpdate

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -3,7 +3,7 @@
 > **Última actualización**: 2025-12-08
 > **Lenguaje**: Zig 0.15.2
 > **Inspiración**: [ratatui](https://github.com/ratatui/ratatui) (Rust TUI library)
-> **Estado**: v1.0 - Implementación completa de todos los widgets de ratatui
+> **Estado**: v1.1 - Implementación completa + optimizaciones de performance
 
 ## Descripción del Proyecto
 
@@ -17,7 +17,7 @@
 
 ## Estado Actual del Proyecto
 
-### Implementación Completa (v1.0) - 2025-12-08
+### Implementación Completa (v1.1) - 2025-12-08
 
 | Componente | Estado | Archivo |
 |------------|--------|---------|
@@ -420,12 +420,19 @@ zig build test --summary all # Tests con detalles
 
 ---
 
-## Próximos Pasos (v1.1+)
+## Optimizaciones de Performance (v1.1)
 
-### Mejoras de Performance
-- [ ] Optimización de buffer diff
+### Implementadas
+- [x] **Symbol compacto**: Almacena UTF-8 directamente (4 bytes max), evita conversión en cada render
+- [x] **Buffer diff**: Iterator que solo retorna celdas modificadas, reduce I/O dramáticamente
+- [x] **Cell.eql()**: Comparación eficiente de celdas para el diff
+- [x] **Buffer.resize()**: Redimensiona preservando contenido existente
+- [x] **writeSymbol()**: Escribe UTF-8 directo sin conversión de codepoint
+
+### Pendientes (v1.2+)
 - [ ] Lazy rendering para widgets grandes
 - [ ] Pooling de memoria para cells
+- [ ] SIMD para operaciones de buffer masivas
 
 ### Funcionalidades Adicionales
 - [ ] Input handling (keyboard events)
@@ -442,11 +449,19 @@ zig build test --summary all # Tests con detalles
 
 ## Historial de Desarrollo
 
+### 2025-12-08 - v1.1 (Performance)
+- Symbol: tipo compacto UTF-8 (4 bytes max)
+- Buffer.diff(): renderizado diferencial eficiente
+- Cell.eql(): comparación optimizada
+- Buffer.resize(): redimensionado con preservación
+- writeSymbol(): output UTF-8 directo
+- Tests: 18 tests (9 nuevos para optimizaciones)
+
 ### 2025-12-08 - v1.0 (Implementación Completa)
 - Implementados todos los widgets de ratatui (13 widgets)
 - Sistema de símbolos completo (braille, half-block, borders, etc.)
 - 103+ tests en widgets
-- Documentación completa
+- Documentación completa (ARCHITECTURE.md, WIDGETS.md, API.md)
 
 ### 2025-12-08 - Inicio del Proyecto
 - Creación de CLAUDE.md

docs/API.md

@@ -171,27 +171,54 @@ const area = Rect.init(0, 0, 80, 24);
 const inner = area.inner(1);  // Rect.init(1, 1, 78, 22)
 ```
 
+### Symbol
+
+Almacenamiento compacto UTF-8 (hasta 4 bytes). Optimizado para evitar conversiones en render.
+
+```zig
+pub const Symbol = struct {
+    data: [4]u8 = .{ ' ', 0, 0, 0 },
+    len: u3 = 1,
+
+    pub const default_val: Symbol = .{};
+    pub const space: Symbol = .{};
+
+    // Constructores
+    pub fn fromSlice(bytes: []const u8) Symbol;
+    pub fn fromCodepoint(cp: u21) Symbol;
+
+    // Acceso
+    pub fn slice(self: Symbol) []const u8;  // Para output directo
+    pub fn eql(self: Symbol, other: Symbol) bool;
+};
+```
+
 ### Cell
 
 ```zig
 pub const Cell = struct {
-    symbol: Symbol,
-    style: Style,
+    symbol: Symbol = Symbol.space,
+    fg: Color = .reset,
+    bg: Color = .reset,
+    modifiers: Modifier = .{},
 
-    pub const default_val: Cell = .{ .symbol = Symbol.default_val, .style = Style.default };
+    pub const empty: Cell = .{};
 
+    // Constructores
+    pub fn init(cp: u21) Cell;
+    pub fn fromStr(s: []const u8) Cell;
+
+    // Modificadores
+    pub fn setStyle(self: *Cell, s: Style) void;
+    pub fn setChar(self: *Cell, cp: u21) void;
+    pub fn setSymbol(self: *Cell, s: []const u8) void;
     pub fn reset(self: *Cell) void;
-    pub fn setChar(self: *Cell, ch: u21) void;
-    pub fn setSymbol(self: *Cell, symbol: []const u8) void;
-    pub fn setStyle(self: *Cell, style: Style) void;
-};
 
-pub const Symbol = struct {
-    data: [4]u8,
-    len: u3,
+    // Comparación (para diff)
+    pub fn eql(self: Cell, other: Cell) bool;
 
-    pub const default_val: Symbol;  // " "
-    pub fn slice(self: Symbol) []const u8;
+    // Legacy accessor
+    pub fn char(self: Cell) u21;  // Decodifica symbol a codepoint
 };
 ```
 
@@ -205,24 +232,41 @@ pub const Buffer = struct {
 
     pub fn init(allocator: Allocator, area: Rect) !Buffer;
     pub fn deinit(self: *Buffer) void;
-    pub fn empty(area: Rect) Buffer;  // No allocation
 
     // Cell access
-    pub fn getCell(self: *Buffer, x: u16, y: u16) ?*Cell;
-    pub fn index(self: Buffer, x: u16, y: u16) ?usize;
+    pub fn getPtr(self: *Buffer, x: u16, y: u16) ?*Cell;
+    pub fn getCell(self: *Buffer, x: u16, y: u16) ?*Cell;  // Alias
+    pub fn get(self: *const Buffer, x: u16, y: u16) ?Cell;
 
     // Setting content
+    pub fn setChar(self: *Buffer, x: u16, y: u16, cp: u21, s: Style) void;
     pub fn setString(self: *Buffer, x: u16, y: u16, text: []const u8, style: Style) u16;
-    pub fn setSpan(self: *Buffer, x: u16, y: u16, span: Span, width: u16) u16;
-    pub fn setLine(self: *Buffer, x: u16, y: u16, line: Line, width: u16) u16;
     pub fn setStyle(self: *Buffer, area: Rect, style: Style) void;
 
     // Filling
-    pub fn fill(self: *Buffer, cell: Cell) void;
-    pub fn fillArea(self: *Buffer, area: Rect, cell: Cell) void;
+    pub fn fill(self: *Buffer, rect: Rect, cp: u21, s: Style) void;
+    pub fn clear(self: *Buffer) void;
 
-    // Merging
+    // Differential rendering (v1.1)
+    pub fn diff(self: *const Buffer, other: *const Buffer) DiffIterator;
+    pub fn resize(self: *Buffer, new_rect: Rect) !void;
     pub fn merge(self: *Buffer, other: *const Buffer) void;
+
+    // Legacy (no-op, for compatibility)
+    pub fn markDirty(self: *Buffer) void;
+    pub fn markClean(self: *Buffer) void;
+};
+
+// Iterator para renderizado diferencial
+pub const DiffIterator = struct {
+    pub fn next(self: *DiffIterator) ?CellUpdate;
+    pub fn countRemaining(self: *DiffIterator) usize;
+};
+
+pub const CellUpdate = struct {
+    x: u16,
+    y: u16,
+    cell: Cell,
 };
 ```
 

docs/ARCHITECTURE.md

@@ -398,16 +398,33 @@ const MyWidget = struct {
 
 ## Performance
 
-### Optimizaciones Actuales
+### Optimizaciones Implementadas (v1.1)
 
-1. **Diff-based rendering**: Solo se envían cambios a la terminal
-2. **Pre-computed symbols**: Braille patterns pre-calculados
-3. **Inline functions**: Funciones críticas marcadas como inline
-4. **Saturating arithmetic**: Uso de `-|` para evitar overflow checks
+1. **Symbol compacto**: Tipo que almacena UTF-8 directamente (4 bytes max)
+   - Evita conversión codepoint→UTF8 en cada render
+   - `fromCodepoint()` y `fromSlice()` para crear symbols
+   - `slice()` retorna bytes listos para output
 
-### Áreas de Mejora Futuras
+2. **Buffer diff**: Sistema de renderizado diferencial
+   - `DiffIterator` compara buffers celda a celda
+   - Solo retorna celdas que cambiaron entre frames
+   - Reduce dramáticamente I/O a terminal
 
-1. Buffer pooling para reutilización
+3. **Cell.eql()**: Comparación eficiente de celdas
+   - Compara symbol, fg, bg, modifiers
+   - Base del sistema de diff
+
+4. **writeSymbol()**: Output UTF-8 directo
+   - Escribe bytes sin conversión
+   - Más eficiente que `writeChar()` con encoding
+
+5. **Pre-computed symbols**: Braille patterns pre-calculados (256 patrones)
+
+6. **Saturating arithmetic**: Uso de `-|` y `+|` para evitar overflow checks
+
+### Áreas de Mejora Futuras (v1.2+)
+
+1. Buffer pooling para reutilización de memoria
 2. Lazy widget evaluation
-3. Dirty region tracking
-4. SIMD para operaciones de buffer
+3. SIMD para operaciones de buffer masivas
+4. Dirty region tracking (solo re-renderizar áreas modificadas)