From 7acf5837635328b96c9256735cff440e3ef7b1e6 Mon Sep 17 00:00:00 2001 From: reugenio Date: Mon, 8 Dec 2025 12:25:52 +0100 Subject: [PATCH] Documentacion actualizada para v1.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 27 ++++++++++---- docs/API.md | 84 +++++++++++++++++++++++++++++++++----------- docs/ARCHITECTURE.md | 35 +++++++++++++----- 3 files changed, 111 insertions(+), 35 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7b2f810..f96c805 100644 --- a/CLAUDE.md +++ b/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 diff --git a/docs/API.md b/docs/API.md index 9934902..492a835 100644 --- a/docs/API.md +++ b/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, }; ``` diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index fdc6650..61e10d9 100644 --- a/docs/ARCHITECTURE.md +++ b/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鈫扷TF8 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)