zcatpdf/CLAUDE.md

zcatpdf - Generador PDF para Zig

Version: v1.0 - RELEASE (FEATURE COMPLETE) Ultima actualizacion: 2025-12-09 Lenguaje: Zig 0.15.2 Repositorio: git@git.reugenio.com:reugenio/zcatpdf.git

---

Informacion para Nueva Conversacion

Que es zcatpdf?

Libreria pura Zig para generacion de documentos PDF. Parte de la familia "zcat*" (zcatui, zcatgui, zcatpdf).

Documentacion Disponible

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

Comandos Esenciales

# Zig path
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig

# Compilar y testear
$ZIG build
$ZIG build test

# Ejecutar ejemplos
./zig-out/bin/hello
./zig-out/bin/invoice
./zig-out/bin/barcode_demo
# etc. (16 ejemplos en total)

Normas de Trabajo

Las normas del equipo estan en:

/mnt/cello2/arno/re/recode/TEAM_STANDARDS/

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

---

Uso Rapido

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

# Remote actual (NOTA: renombrar en Forgejo a zcatpdf)
git remote: git@git.reugenio.com:reugenio/zcatpdf.git

# Branch principal
main

IMPORTANTE tras renombrar directorio:

# 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
• fpdf2 (Python) - Inspiracion de la API
• Zig Documentation

---

zcatpdf v1.0 - Generador PDF para Zig Feature Complete - 2025-12-09