From 9ae8758ed8af4ddc6b3055e58f69f157a67f427d Mon Sep 17 00:00:00 2001 From: reugenio Date: Tue, 9 Dec 2025 02:15:44 +0100 Subject: [PATCH] docs: Update CLAUDE.md with comprehensive context for new conversations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prepares documentation for directory rename (zpdf → zcatpdf): - Complete project overview and feature status - Documentation references (README.md, FUTURE_IMPROVEMENTS.md) - Architecture diagram and usage examples - Git instructions including post-rename steps - zcat* family ecosystem information 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 899 +++++++++++------------------------------------------- 1 file changed, 174 insertions(+), 725 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2d4711d..9416bc3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,757 +1,206 @@ # zcatpdf - Generador PDF para Zig +> **Version**: v1.0 - RELEASE (FEATURE COMPLETE) > **Ultima actualizacion**: 2025-12-09 > **Lenguaje**: Zig 0.15.2 -> **Estado**: v1.0 - RELEASE (FEATURE COMPLETE) -> **Fuente principal**: fpdf2 (Python) - https://github.com/py-pdf/fpdf2 - -## Descripcion del Proyecto - -**zcatpdf** es una libreria pura Zig para generacion de documentos PDF. Compila a un binario unico con minimas dependencias. - -**Filosofia**: -- Minimas dependencias (libdeflate para compresion) -- API simple y directa inspirada en fpdf2 -- Enfocado en generacion de facturas/documentos comerciales -- Soporte completo: texto, tablas, imagenes, links, graficos vectoriales - -**Caracteristicas principales**: -- Sistema de texto completo (cell, multiCell, alineacion, word wrap) -- 14 fuentes Type1 standard (Helvetica, Times, Courier, etc.) -- Imagenes JPEG y PNG (con alpha/transparencia) -- Compresion FlateDecode para streams e imagenes -- Table helper para tablas formateadas -- Paginacion automatica (numeros de pagina, headers, footers) -- Links clickeables (URLs externas + links internos entre paginas) -- Bookmarks/Outline para navegacion en sidebar -- Curvas Bezier, circulos, elipses, arcos -- Transformaciones (rotacion, escala, skew, traslacion) -- Transparencia/Opacidad (fill y stroke alpha) -- Gradientes lineales y radiales (Shading Patterns) -- Barcodes: Code128 (1D) y QR Code (2D) -- TrueType font parsing (family, metrics, glyph widths) -- Security: RC4 encryption, permission flags -- Forms: AcroForms (text fields, checkboxes) -- SVG import (basic path/shape support) -- Templates: Reusable document layouts -- Markdown: Styled text (bold, italic, links, headings, lists) -- Colores RGB, CMYK, Grayscale +> **Repositorio**: git@git.reugenio.com:reugenio/zcatpdf.git --- -## Estado Actual - v1.0 +## Informacion para Nueva Conversacion -### Funcionalidades Implementadas +### Que es zcatpdf? -| Categoria | Funcionalidad | Estado | -|-----------|---------------|--------| -| **Documento** | | | -| | Crear PDF 1.4 | OK | -| | Metadatos (titulo, autor, etc.) | OK | -| | Multiples paginas | OK | -| | Tamanos estandar (A4, Letter, A3, A5, Legal) | OK | -| | Compresion FlateDecode configurable | OK | -| | Bookmarks/Outline | OK | -| **Texto** | | | -| | drawText() - texto en posicion | OK | -| | cell() - celda con bordes/relleno | OK | -| | multiCell() - word wrap automatico | OK | -| | Alineacion (left, center, right) | OK | -| | 14 fuentes Type1 standard | OK | -| **Graficos** | | | -| | Lineas | OK | -| | Rectangulos (stroke, fill) | OK | -| | Curvas Bezier (cubicas, cuadraticas) | OK | -| | Circulos y elipses | OK | -| | Arcos | OK | -| | Colores RGB/CMYK/Gray | OK | -| **Transformaciones** | | | -| | Rotacion (alrededor de punto) | OK | -| | Escala (desde punto) | OK | -| | Traslacion | OK | -| | Skew/Shear | OK | -| | Matriz personalizada | OK | -| | saveState()/restoreState() | OK | -| **Transparencia** | | | -| | Fill opacity (0.0-1.0) | OK | -| | Stroke opacity (0.0-1.0) | OK | -| | ExtGState resources | OK | -| **Gradientes** | | | -| | Linear gradients (horizontal, vertical, diagonal) | OK | -| | Radial gradients (circle, ellipse) | OK | -| | Shading Patterns (Type 2, Type 3) | OK | -| **Barcodes** | | | -| | Code128 (1D barcode) | OK | -| | QR Code (2D barcode) | OK | -| | Error correction levels (L, M, Q, H) | OK | -| | drawCode128() / drawCode128WithText() | OK | -| | drawQRCode() | OK | -| **TrueType Fonts** | | | -| | TTF file parsing | OK | -| | Font metrics (ascender, descender, etc.) | OK | -| | Glyph widths | OK | -| | Character to glyph mapping (cmap) | OK | -| | addTtfFontFromFile() | OK | -| **Security** | | | -| | RC4 cipher (40/128-bit) | OK | -| | User/Owner passwords | OK | -| | Permission flags | OK | -| | MD5 key derivation | OK | -| | Encryption module | OK | -| **Forms** | | | -| | TextField | OK | -| | CheckBox | OK | -| | Field flags | OK | -| | AcroForm basics | OK | -| **SVG** | | | -| | Path parsing | OK | -| | Basic shapes (rect, circle, ellipse, line) | OK | -| | Colors (fill, stroke) | OK | -| | PDF content generation | OK | -| **Templates** | | | -| | Template struct | OK | -| | Named regions | OK | -| | Fixed content | OK | -| | invoiceTemplate() | OK | -| | letterTemplate() | OK | -| **Markdown** | | | -| | Bold (**text**) | OK | -| | Italic (*text*) | OK | -| | Bold+Italic (***text***) | OK | -| | Strikethrough (~~text~~) | OK | -| | Links ([text](url)) | OK | -| | Headings (#, ##, ###) | OK | -| | Bullet lists (- item) | OK | -| | Numbered lists (1. item) | OK | -| **Imagenes** | | | -| | JPEG embedding (passthrough) | OK | -| | PNG embedding (RGB, RGBA, Grayscale, Indexed) | OK | -| | PNG alpha channel (soft masks) | OK | -| | image() / imageFit() | OK | -| | Aspect ratio preservation | OK | -| **Compresion** | | | -| | FlateDecode para content streams | OK | -| | FlateDecode para imagenes PNG | OK | -| | Nivel configurable (0-12) | OK | -| | Heuristica inteligente | OK | -| **Tablas** | | | -| | Table helper | OK | -| | header(), row(), footer() | OK | -| | Alineacion por columna | OK | -| | Estilos personalizados | OK | -| **Paginacion** | | | -| | Numeros de pagina | OK | -| | Headers automaticos | OK | -| | Footers automaticos | OK | -| | skip_pages option | OK | -| **Links** | | | -| | URL links clickeables | OK | -| | Internal page links | OK | -| | Visual styling (azul+subrayado) | OK | -| | Link annotations | OK | +Libreria pura Zig para generacion de documentos PDF. Parte de la familia "zcat*" (zcatui, zcatgui, zcatpdf). -### Tests y Ejemplos +### Documentacion Disponible -- **125+ tests** unitarios pasando -- **16 ejemplos** funcionales: - - `hello.zig` - PDF minimo - - `invoice.zig` - Factura completa - - `text_demo.zig` - Sistema de texto - - `image_demo.zig` - Imagenes JPEG y PNG - - `table_demo.zig` - Table helper - - `pagination_demo.zig` - Paginacion multi-pagina - - `links_demo.zig` - Links clickeables - - `bookmarks_demo.zig` - Bookmarks en sidebar - - `curves_demo.zig` - Bezier, circulos, elipses, arcos - - `transforms_demo.zig` - Rotacion, escala, skew - - `transparency_demo.zig` - Opacidad/alpha - - `gradient_demo.zig` - Gradientes lineales y radiales - - `barcode_demo.zig` - Code128 y QR codes - - `ttf_demo.zig` - TrueType font parsing - - `template_demo.zig` - Document templates - - `markdown_demo.zig` - Markdown styled text +| Archivo | Contenido | +|---------|-----------| +| `README.md` | **Manual de referencia completo** - API, ejemplos de codigo, tipos, archivos | +| `FUTURE_IMPROVEMENTS.md` | **Mejoras futuras detalladas** - TTF embedding, encryption integration, forms output, SVG avanzado | +| `CLAUDE.md` | Este archivo - contexto del proyecto | ---- - -## Arquitectura - -``` -zcatpdf/ -├── CLAUDE.md # Documentacion del proyecto -├── build.zig # Sistema de build -├── src/ -│ ├── root.zig # Exports publicos -│ ├── pdf.zig # Pdf facade (API principal) -│ ├── page.zig # Page + texto + links + transformaciones -│ ├── content_stream.zig # Operadores PDF -│ ├── table.zig # Table helper -│ ├── pagination.zig # Paginacion, headers, footers -│ ├── links.zig # Link types -│ ├── outline.zig # Bookmarks/Outline -│ ├── security/ -│ │ ├── mod.zig # Security exports -│ │ ├── rc4.zig # RC4 cipher -│ │ └── encryption.zig # PDF encryption handler -│ ├── forms/ -│ │ ├── mod.zig # Forms exports -│ │ └── field.zig # TextField, CheckBox -│ ├── svg/ -│ │ ├── mod.zig # SVG exports -│ │ └── parser.zig # SVG parser -│ ├── template/ -│ │ ├── mod.zig # Template exports -│ │ └── template.zig # Template, Region definitions -│ ├── markdown/ -│ │ ├── mod.zig # Markdown exports -│ │ └── markdown.zig # MarkdownRenderer, TextSpan -│ ├── fonts/ -│ │ ├── type1.zig # 14 fuentes Type1 + metricas -│ │ └── ttf.zig # TrueType font parser -│ ├── graphics/ -│ │ ├── color.zig # Color (RGB, CMYK, Gray) -│ │ ├── extgstate.zig # Extended Graphics State (transparency) -│ │ └── gradient.zig # Linear/Radial gradients -│ ├── barcodes/ -│ │ ├── mod.zig # Barcode exports -│ │ ├── code128.zig # Code128 1D barcode -│ │ └── qr.zig # QR Code 2D barcode -│ ├── images/ -│ │ ├── jpeg.zig # JPEG parser -│ │ ├── png.zig # PNG parser + unfiltering -│ │ └── image_info.zig # ImageInfo struct -│ ├── compression/ -│ │ ├── mod.zig # Compression exports -│ │ └── zlib.zig # libdeflate wrapper -│ ├── objects/ -│ │ └── base.zig # PageSize, Orientation -│ └── output/ -│ └── producer.zig # Serializa PDF + images + links + outline -└── examples/ - ├── hello.zig - ├── invoice.zig - ├── text_demo.zig - ├── image_demo.zig - ├── table_demo.zig - ├── pagination_demo.zig - ├── links_demo.zig - ├── bookmarks_demo.zig - ├── curves_demo.zig - ├── transforms_demo.zig - ├── transparency_demo.zig - ├── gradient_demo.zig - ├── barcode_demo.zig - ├── ttf_demo.zig - ├── template_demo.zig - └── markdown_demo.zig -``` - ---- - -## API Quick Reference - -### Documento Basico - -```zig -const zcatpdf = @import("zcatpdf"); - -var doc = zcatpdf.Pdf.init(allocator, .{}); -defer doc.deinit(); - -doc.setTitle("Mi Documento"); -var page = try doc.addPage(.{}); - -try page.setFont(.helvetica_bold, 24); -try page.drawText(50, 750, "Hello, PDF!"); - -try doc.save("output.pdf"); -``` - -### Celdas y Tablas - -```zig -// cell() simple -try page.cell(100, 20, "Hello", zcatpdf.Border.all, .center, true); - -// multiCell con word wrap -try page.multiCell(400, null, texto_largo, zcatpdf.Border.none, .left, false); - -// Table helper -const widths = [_]f32{ 200, 100, 100 }; -var table = zcatpdf.Table.init(page, .{ - .col_widths = &widths, -}); -try table.header(&.{ "Producto", "Qty", "Precio" }); -try table.row(&.{ "Item A", "10", "$50" }); -try table.footer(&.{ "Total", "", "$50" }); -``` - -### Imagenes - -```zig -const img_idx = try doc.addJpegImageFromFile("foto.jpg"); -const info = doc.getImage(img_idx).?; -try page.image(img_idx, info, 50, 500, 200, 150); -``` - -### Curvas y Formas - -```zig -// Curva Bezier cubica -try page.drawBezier(x0, y0, x1, y1, x2, y2, x3, y3); - -// Circulo -try page.drawCircle(cx, cy, radius); -try page.fillCircle(cx, cy, radius); - -// Elipse -try page.drawEllipse(cx, cy, rx, ry); -try page.fillEllipse(cx, cy, rx, ry); - -// Arco -try page.drawArc(cx, cy, rx, ry, start_deg, end_deg); -``` - -### Transformaciones - -```zig -// Rotar alrededor de un punto -try page.saveState(); -try page.rotate(45, center_x, center_y); // 45 grados -// ... dibujar contenido rotado ... -try page.restoreState(); - -// Escalar -try page.scale(2.0, 1.5, cx, cy); // 2x horizontal, 1.5x vertical - -// Skew/Shear -try page.skew(15, 0); // 15 grados en X - -// Trasladar -try page.translate(100, 50); -``` - -### Transparencia - -```zig -// Opacidad de relleno -try page.setFillOpacity(0.5); // 50% transparente - -// Opacidad de trazo -try page.setStrokeOpacity(0.75); // 75% opaco - -// Ambos a la vez -try page.setOpacity(0.3); // 30% opaco - -// Restaurar opacidad completa -try page.setOpacity(1.0); -``` - -### Gradientes - -```zig -// Gradiente lineal en rectangulo -try page.linearGradientRect(x, y, width, height, Color.red, Color.blue, .horizontal); -try page.linearGradientRect(x, y, width, height, Color.green, Color.yellow, .vertical); -try page.linearGradientRect(x, y, width, height, Color.purple, Color.cyan, .diagonal); - -// Gradiente radial en circulo (centro a borde) -try page.radialGradientCircle(cx, cy, radius, Color.white, Color.blue); - -// Gradiente radial en elipse -try page.radialGradientEllipse(cx, cy, rx, ry, Color.yellow, Color.red); -``` - -### Barcodes - -```zig -// Code128 1D barcode -try page.drawCode128(x, y, "ABC-12345", 50, 1.5); // height=50, module_width=1.5 - -// Code128 con texto debajo -try page.drawCode128WithText(x, y, "ABC-12345", 50, 1.5, true); - -// QR Code 2D barcode -try page.drawQRCode(x, y, "HTTPS://GITHUB.COM", 100, zcatpdf.QRCode.ErrorCorrection.M); - -// Error correction levels: -// .L - Low (7% recovery) -// .M - Medium (15% recovery) -// .Q - Quartile (25% recovery) -// .H - High (30% recovery) -``` - -### TrueType Fonts - -```zig -// Load TTF font from file -const font_idx = try pdf.addTtfFontFromFile("/path/to/font.ttf"); -const font = pdf.getTtfFont(font_idx).?; - -// Get font information -std.debug.print("Family: {s}\n", .{font.family_name}); -std.debug.print("Units/EM: {d}\n", .{font.units_per_em}); -std.debug.print("Ascender: {d}\n", .{font.ascender}); -std.debug.print("Descender: {d}\n", .{font.descender}); -std.debug.print("Num glyphs: {d}\n", .{font.num_glyphs}); - -// Get character width -const glyph_id = font.getGlyphIndex('A'); -const width = font.getGlyphWidth(glyph_id); - -// Calculate string width in points -const text_width = font.stringWidth("Hello", 12.0); - -// Note: Full TTF embedding for rendering text requires CIDFont Type 2 -// output which is planned for a future version. -``` - -### Bookmarks - -```zig -// Agregar bookmark que apunta a pagina -try doc.addBookmark("Capitulo 1", 0); // pagina 0 - -// Con posicion Y especifica -try doc.addBookmarkAt("Seccion 1.1", 0, 500); - -// Los bookmarks aparecen en el sidebar del lector PDF -``` - -### Links Clickeables - -```zig -// URL link con visual styling -_ = try page.urlLink(100, 700, "Click aqui", "https://example.com"); - -// O desde posicion actual -_ = try page.writeUrlLink("Visitar web", "https://example.com"); - -// Link interno (saltar a pagina) -try page.addInternalLink(2, 100, 700, 150, 20); // page 2 -``` - -### Paginacion - -```zig -// Numeros de pagina -try zcatpdf.Pagination.addPageNumbers(&doc, .{ - .format = "Page {PAGE} of {PAGES}", - .position = .bottom_center, -}); - -// Header con linea -try zcatpdf.addHeader(&doc, "Documento", .{ - .draw_line = true, -}); -``` - ---- - -## Comandos +### Comandos Esenciales ```bash # Zig path ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig -# Compilar +# Compilar y testear $ZIG build - -# Tests $ZIG build test -# Ejemplos +# Ejecutar ejemplos ./zig-out/bin/hello ./zig-out/bin/invoice -./zig-out/bin/text_demo -./zig-out/bin/image_demo -./zig-out/bin/table_demo -./zig-out/bin/pagination_demo -./zig-out/bin/links_demo -./zig-out/bin/bookmarks_demo -./zig-out/bin/curves_demo -./zig-out/bin/transforms_demo -./zig-out/bin/transparency_demo -./zig-out/bin/gradient_demo ./zig-out/bin/barcode_demo -./zig-out/bin/ttf_demo +# etc. (16 ejemplos en total) ``` ---- - -## Roadmap Completado - -### Fase 1 - Core (COMPLETADO) -- [x] Estructura PDF 1.4 -- [x] Paginas multiples -- [x] Texto basico -- [x] Graficos (lineas, rectangulos) -- [x] Colores - -### Fase 2 - Texto Avanzado (COMPLETADO) -- [x] cell() / cellAdvanced() -- [x] multiCell() con word wrap -- [x] Alineacion -- [x] Bordes - -### Fase 3 - Imagenes (COMPLETADO) -- [x] JPEG embedding -- [x] image() / imageFit() -- [x] PNG embedding completo - -### Fase 4 - Utilidades (COMPLETADO) -- [x] Table helper -- [x] Paginacion -- [x] Headers/Footers -- [x] Links visuales - -### Fase 5 - Links Clickeables (COMPLETADO) -- [x] URL annotations -- [x] Internal page links -- [x] Link annotations en PDF - -### Fase 6 - PNG + Compresion (COMPLETADO) -- [x] Integracion libdeflate-zig -- [x] PNG parsing completo (RGB, RGBA, Grayscale, Indexed) -- [x] PNG unfiltering (None, Sub, Up, Average, Paeth) -- [x] Soft masks para canal alpha -- [x] FlateDecode para content streams -- [x] Compresion configurable (nivel 0-12) -- [x] Heuristica inteligente (min_size, min_ratio) - -### Fase 7 - Bookmarks/Outline (COMPLETADO) -- [x] OutlineItem struct -- [x] addBookmark() / addBookmarkAt() -- [x] Outline en sidebar del lector PDF - -### Fase 8 - Curvas Bezier (COMPLETADO) -- [x] drawBezier() - curvas cubicas -- [x] drawQuadBezier() - curvas cuadraticas -- [x] drawCircle() / fillCircle() -- [x] drawEllipse() / fillEllipse() -- [x] drawArc() - -### Fase 9 - Transformaciones (COMPLETADO) -- [x] rotate() - rotacion alrededor de punto -- [x] scale() - escala desde punto -- [x] translate() - traslacion -- [x] skew() - deformacion -- [x] transform() - matriz personalizada -- [x] saveState() / restoreState() - -### Fase 10 - Transparencia (COMPLETADO) -- [x] ExtGState para opacidad -- [x] setFillOpacity() -- [x] setStrokeOpacity() -- [x] setOpacity() - -### Fase 11 - Gradientes (COMPLETADO) -- [x] LinearGradient (horizontal, vertical, diagonal) -- [x] RadialGradient (circle, ellipse) -- [x] Shading Patterns Type 2 (axial) y Type 3 (radial) -- [x] linearGradientRect() -- [x] radialGradientCircle() -- [x] radialGradientEllipse() - -### Fase 12 - Barcodes (COMPLETADO) -- [x] Code128 1D barcode (ASCII 0-127) -- [x] Code Sets A, B, C con switching automatico -- [x] QR Code 2D barcode (ISO/IEC 18004) -- [x] Error correction levels (L, M, Q, H) -- [x] drawCode128() / drawCode128WithText() -- [x] drawQRCode() - -### Fase 13 - TTF Fonts (COMPLETADO) -- [x] TrueType font file parsing -- [x] Font metrics (units_per_em, ascender, descender, etc.) -- [x] Glyph width tables -- [x] Character to glyph mapping (cmap format 0, 4, 6, 12) -- [x] addTtfFontFromFile() -- [x] stringWidth() calculation -- [ ] Full TTF embedding for PDF rendering (CIDFont Type 2) - Future - -### Fase 14 - Security/Encryption (COMPLETADO) -- [x] RC4 stream cipher (40-bit and 128-bit) -- [x] PDF Standard Security Handler -- [x] User/Owner password handling -- [x] Permission flags (print, modify, copy, annotate, etc.) -- [x] MD5-based key derivation -- [x] Object key generation -- [ ] Full PDF output integration - Future - -### Fase 15 - Forms/AcroForms (COMPLETADO) -- [x] TextField struct (name, position, size) -- [x] CheckBox struct -- [x] FieldFlags (readonly, required, multiline, password) -- [x] FormField union type -- [x] toFormField() conversion -- [ ] Full PDF AcroForm output integration - Future - -### Fase 16 - SVG Import (COMPLETADO) -- [x] SvgParser struct -- [x] Basic shapes (rect, circle, ellipse, line) -- [x] Path element with commands -- [x] PathCommand enum (MoveTo, LineTo, CurveTo, etc.) -- [x] Color parsing (fill, stroke) -- [x] toPdfContent() - generates PDF operators -- [ ] Text elements - Future -- [ ] Transforms - Future - -### Fase 17 - Templates (COMPLETADO) -- [x] Template struct with named regions -- [x] TemplateRegion (position, size, type) -- [x] RegionType enum (text, image, table, custom) -- [x] FixedContent for repeating elements -- [x] invoiceTemplate() predefined -- [x] letterTemplate() predefined -- [x] template_demo.zig ejemplo - -### Fase 18 - Markdown Styling (COMPLETADO) -- [x] MarkdownRenderer struct -- [x] SpanStyle (bold, italic, underline, strikethrough) -- [x] TextSpan with style, color, url, font_size -- [x] Inline parsing: **bold**, *italic*, ***both***, ~~strike~~ -- [x] Links: [text](url) -- [x] Headings: #, ##, ### -- [x] Lists: - bullet, 1. numbered -- [x] fontForStyle() helper -- [x] markdown_demo.zig ejemplo - -### Futuro - -| Fase | Nombre | Prioridad | -|------|--------|-----------| -| 19 | Mejoras de Calidad | CONTINUA | - ---- - -## Historial - -### 2025-12-09 - v0.16 (Markdown Styling) - FEATURE COMPLETE -- MarkdownRenderer para texto con estilo -- SpanStyle (bold, italic, underline, strikethrough) -- TextSpan con style, color, url, font_size -- Parsing de: **bold**, *italic*, ***bold+italic*** -- Strikethrough: ~~text~~ -- Links: [text](url) -- Headings: #, ##, ### -- Lists: - bullet, 1. numbered -- fontForStyle() helper function -- markdown_demo.zig ejemplo -- 125+ tests, 16 ejemplos - -### 2025-12-09 - v0.15 (Templates) -- Template struct con regiones nombradas -- TemplateRegion para definir areas de contenido -- FixedContent para elementos repetitivos -- invoiceTemplate() y letterTemplate() predefinidos -- template_demo.zig ejemplo -- 120+ tests, 15 ejemplos - -### 2025-12-09 - v0.14 (SVG Import) -- SvgParser para importar graficos vectoriales -- Soporte para rect, circle, ellipse, line, path -- PathCommand para curvas y lineas -- toPdfContent() genera operadores PDF -- svg/mod.zig, parser.zig - -### 2025-12-09 - v0.13 (Forms) -- TextField y CheckBox structs -- FieldFlags (readonly, required, multiline, password) -- FormField union type -- forms/mod.zig, field.zig - -### 2025-12-09 - v0.12 (Security) -- RC4 stream cipher (40-bit and 128-bit) -- PDF Standard Security Handler -- User/Owner password processing -- Permission flags (Permissions struct) -- MD5-based key derivation (Algorithms 3.1-3.5) -- security/mod.zig, rc4.zig, encryption.zig -- 100+ tests - -### 2025-12-09 - v0.11 (TTF Fonts) -- TrueType font file parsing (tables: head, hhea, maxp, hmtx, cmap, name, OS/2, post) -- Font metrics extraction -- Glyph width tables for string width calculation -- Character to glyph mapping (cmap formats 0, 4, 6, 12) -- addTtfFontFromFile(), getTtfFont() -- ttf_demo.zig ejemplo -- 14 ejemplos, 95+ tests - -### 2025-12-09 - v0.10 (Barcodes) -- Code128 1D barcode con Code Sets A, B, C -- QR Code 2D barcode con error correction levels -- drawCode128(), drawCode128WithText(), drawQRCode() -- barcode_demo.zig ejemplo -- 13 ejemplos, 90+ tests - -### 2025-12-09 - v0.9 (Gradientes) -- Linear gradients (horizontal, vertical, diagonal) -- Radial gradients (circle, ellipse) -- Shading Patterns Type 2 (axial) y Type 3 (radial) -- linearGradientRect(), radialGradientCircle(), radialGradientEllipse() -- GradientData, LinearGradient, RadialGradient types -- gradient_demo.zig ejemplo -- 12 ejemplos, 85+ tests - -### 2025-12-08 - v0.8 (Bookmarks + Bezier + Transforms + Transparency) -- Bookmarks/Outline para navegacion en sidebar -- Curvas Bezier (cubicas y cuadraticas) -- Circulos, elipses y arcos -- Transformaciones: rotacion, escala, traslacion, skew -- saveState()/restoreState() para limitar transformaciones -- Transparencia via ExtGState -- setFillOpacity(), setStrokeOpacity(), setOpacity() -- 4 nuevos ejemplos -- 85+ tests pasando - -### 2025-12-08 - v0.7 (PNG + Compresion) -- Integracion libdeflate-zig para compresion -- PNG embedding completo (RGB, RGBA, Grayscale, Indexed) -- PNG unfiltering (5 filtros) -- Soft masks para transparencia -- FlateDecode para content streams -- Compresion configurable con heuristica -- 82+ tests pasando - -### 2025-12-08 - v0.6 (Links Clickeables) -- Link annotations clickeables en PDF -- addUrlLink() / addInternalLink() en Page -- urlLink() / writeUrlLink() combinan visual + annotation -- OutputProducer genera /Annots en pages -- links_demo.zig ejemplo con 2 paginas -- 7 ejemplos, ~70 tests - -### 2025-12-08 - v0.5 (Utilidades) -- Table helper -- Pagination (numeros de pagina) -- Headers/Footers automaticos -- Links visuales - -### 2025-12-08 - v0.4 (Imagenes) -- JPEG embedding -- image() / imageFit() - -### 2025-12-08 - v0.3 (Texto) -- cell() / multiCell() -- Word wrap, alineacion - -### 2025-12-08 - v0.2 (Core) -- Estructura inicial - -### 2025-12-08 - v0.1 (Setup) -- Setup inicial del proyecto - ---- - -## Equipo +### Normas de Trabajo +Las normas del equipo estan en: ``` /mnt/cello2/arno/re/recode/TEAM_STANDARDS/ -git remote: git@git.reugenio.com:reugenio/zcatpdf.git +``` + +**Reglas clave para este proyecto:** +- Nombres en minusculas: `zcatpdf` (no ZcatPDF, no zCatPdf) +- Import: `@import("zcatpdf")` +- Doc comments (`///`) en funciones publicas +- Codigo idiomatico Zig (snake_case, error handling explicito) + +--- + +## Estado del Proyecto + +### FEATURE COMPLETE - v1.0 + +La libreria esta completa para uso en produccion. Todas las funcionalidades planificadas estan implementadas: + +| Categoria | Funcionalidades | +|-----------|-----------------| +| **Documento** | PDF 1.4, metadatos, multiples paginas, compresion FlateDecode | +| **Texto** | drawText, cell, multiCell, word wrap, 14 fuentes Type1 | +| **Graficos** | Lineas, rectangulos, curvas Bezier, circulos, elipses, arcos | +| **Colores** | RGB, CMYK, Grayscale, colores predefinidos | +| **Imagenes** | JPEG, PNG (con alpha/transparencia) | +| **Tablas** | Table helper con headers, rows, footers | +| **Links** | URLs clickeables, links internos entre paginas | +| **Bookmarks** | Navegacion en sidebar del lector PDF | +| **Transformaciones** | Rotacion, escala, traslacion, skew | +| **Transparencia** | Fill y stroke opacity (0.0-1.0) | +| **Gradientes** | Lineales y radiales | +| **Barcodes** | Code128 (1D), QR Code (2D) | +| **TTF Fonts** | Parsing de TrueType (metricas, anchos de glyph) | +| **Security** | RC4 encryption module (40/128-bit) | +| **Forms** | TextField, CheckBox (structs, no output aun) | +| **SVG** | Import basico (shapes, paths) | +| **Templates** | Layouts reutilizables (invoice, letter) | +| **Markdown** | Texto con estilos (bold, italic, links, headings, lists) | + +### Tests y Ejemplos + +- **125+ tests** unitarios +- **16 ejemplos** funcionales en `examples/` + +--- + +## Arquitectura de Archivos + +``` +zcatpdf/ +├── CLAUDE.md # Este archivo +├── README.md # Manual de referencia completo +├── FUTURE_IMPROVEMENTS.md # Mejoras futuras detalladas +├── build.zig # Sistema de build +├── build.zig.zon # Dependencias (libdeflate) +├── src/ +│ ├── root.zig # Exports publicos (@import("zcatpdf")) +│ ├── pdf.zig # Pdf struct - API principal +│ ├── page.zig # Page - dibujo, texto, transformaciones +│ ├── content_stream.zig # Operadores PDF de bajo nivel +│ ├── table.zig # Table helper +│ ├── pagination.zig # Numeros de pagina, headers, footers +│ ├── links.zig # Link types +│ ├── outline.zig # Bookmarks +│ ├── fonts/ # Type1 + TrueType +│ ├── graphics/ # Color, ExtGState, Gradient +│ ├── images/ # JPEG, PNG parsers +│ ├── barcodes/ # Code128, QR +│ ├── compression/ # libdeflate wrapper +│ ├── security/ # RC4, Encryption +│ ├── forms/ # TextField, CheckBox +│ ├── svg/ # SVG parser +│ ├── template/ # Template system +│ ├── markdown/ # Markdown renderer +│ ├── objects/ # PageSize, Orientation +│ └── output/ # PDF serialization +└── examples/ # 16 demos ejecutables ``` --- -**zcatpdf - Generador PDF para Zig** -*v1.0 - RELEASE (FEATURE COMPLETE) - 2025-12-09* +## Uso Rapido + +```zig +const zcatpdf = @import("zcatpdf"); + +pub fn main() !void { + var gpa = std.heap.GeneralPurposeAllocator(.{}){}; + defer _ = gpa.deinit(); + const allocator = gpa.allocator(); + + var pdf = zcatpdf.Pdf.init(allocator, .{}); + defer pdf.deinit(); + + pdf.setTitle("Mi Documento"); + + var page = try pdf.addPage(.{}); + try page.setFont(.helvetica_bold, 24); + try page.drawText(50, 750, "Hello, PDF!"); + + try pdf.save("output.pdf"); +} +``` + +--- + +## Mejoras Futuras (No Criticas) + +Ver `FUTURE_IMPROVEMENTS.md` para detalles completos: + +1. **TTF Font Embedding** - Embeber TTF para renderizar texto (CIDFont Type 2) +2. **PDF Encryption Integration** - Integrar RC4 con OutputProducer +3. **AcroForms Output** - Generar campos de formulario en PDF final +4. **SVG Avanzado** - text, transforms, gradients en SVG +5. **Markdown Avanzado** - code blocks, tables, images + +--- + +## Git + +```bash +# Remote actual (NOTA: renombrar en Forgejo a zcatpdf) +git remote: git@git.reugenio.com:reugenio/zcatpdf.git + +# Branch principal +main +``` + +**IMPORTANTE tras renombrar directorio:** +```bash +# Despues de: mv zpdf zcatpdf +cd /mnt/cello2/arno/re/recode/zig/zcatpdf +git remote set-url origin git@git.reugenio.com:reugenio/zcatpdf.git +``` + +--- + +## Familia zcat* + +| Proyecto | Descripcion | +|----------|-------------| +| **zcatui** | TUI library (terminal UI, como ratatui) | +| **zcatgui** | GUI library (immediate mode, SDL2 backend) | +| **zcatpdf** | PDF generation library | + +Todos siguen las mismas convenciones: +- 100% Zig +- Minimas dependencias +- Nombres en minusculas +- Open source ready + +--- + +## Referencias Externas + +- [PDF Reference 1.4](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf) +- [fpdf2 (Python)](https://github.com/py-pdf/fpdf2) - Inspiracion de la API +- [Zig Documentation](https://ziglang.org/documentation/master/) + +--- + +**zcatpdf v1.0** - Generador PDF para Zig +*Feature Complete - 2025-12-09*