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: ssh://git@git.reugenio.com:2222/reugenio/zcatpdf.git Forgejo Web: https://git.reugenio.com/reugenio/zcatpdf

---

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
CLAUDE.md	Este archivo - contexto del proyecto
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
docs/ARQUITECTURA_FPDF2.md	Analisis de fpdf2 (Python) - arquitectura de referencia
docs/ARQUITECTURA_ZPDF.md	Diseno inicial del proyecto (historico)
docs/PLAN_MAESTRO_ZPDF.md	Plan original de implementacion (completado)

Normas del Equipo (TEAM_STANDARDS)

Ubicacion: /mnt/cello2/arno/re/recode/TEAM_STANDARDS/

Documentacion centralizada para todos los proyectos:

• INFRASTRUCTURE/FORGEJO_GIT_SERVER.md - Servidor git, tokens, API
• INTEGRATION_GUIDE.md - Guia de integracion de proyectos
• NORMAS_PATRONES_DESARROLLO.md - Patrones y normas de desarrollo

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)

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
origin: ssh://git@git.reugenio.com:2222/reugenio/zcatpdf.git

# Branch principal
main

# Comandos comunes
git status
git add -A && git commit -m "mensaje"
git push

Nota: El proyecto fue renombrado de zpdf a zcatpdf el 2025-12-09. El repositorio en Forgejo y el remote local ya estan actualizados.

---

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