zcatpdf/CLAUDE.md

zpdf - Generador PDF para Zig

Ultima actualizacion: 2025-12-08 Lenguaje: Zig 0.15.2 Estado: v0.1 - Core funcional, en desarrollo activo Inspiracion: gofpdf (Go), fpdf (PHP)

Descripcion del Proyecto

zpdf es una libreria pura Zig para generacion de documentos PDF. Sin dependencias externas, compila a un binario unico.

Filosofia:

• Zero dependencias (100% Zig puro)
• API simple y directa
• Enfocado en generacion de facturas/documentos comerciales
• Soporte para texto, tablas, imagenes y formas basicas
• Calidad open source (doc comments, codigo claro)

Objetivo: Ser el pilar para generar PDFs en Zig con codigo 100% propio, replicando funcionalidad de librerias maduras como gofpdf.

---

Estado Actual del Proyecto

Implementacion v0.1 (Core Funcional)

Componente	Estado	Archivo
Document
Document init/deinit	✅	src/root.zig
addPage (standard sizes)	✅	src/root.zig
addPageCustom	✅	src/root.zig
render() to buffer	✅	src/root.zig
saveToFile()	✅	src/root.zig
Page
Page init/deinit	✅	src/root.zig
setFont	✅	src/root.zig
drawText	✅	src/root.zig
setFillColor	✅	src/root.zig
setStrokeColor	✅	src/root.zig
setLineWidth	✅	src/root.zig
drawLine	✅	src/root.zig
drawRect	✅	src/root.zig
fillRect	✅	src/root.zig
drawFilledRect	✅	src/root.zig
Types
PageSize enum (A4, Letter, etc.)	✅	src/root.zig
Font enum (14 Type1 fonts)	✅	src/root.zig
Color struct (RGB)	✅	src/root.zig

Tests

Categoria	Tests	Estado
Create empty document	1	✅
Add page	1	✅
Render minimal document	1	✅
Font names	1	✅
Color conversion	1	✅
Graphics operations	1	✅
Total	6	✅

Ejemplos

Ejemplo	Descripcion	Estado
hello.zig	PDF minimo con texto y formas	✅
invoice.zig	Factura completa realista	✅

---

Roadmap

Fase 1 - Core (COMPLETADO)

• Estructura documento PDF 1.4
• Paginas (A4, Letter, A3, A5, Legal, custom)
• Texto basico (14 fuentes Type1 built-in)
• Lineas y rectangulos
• Colores RGB
• Serializacion correcta

Fase 2 - Texto Avanzado (PENDIENTE)

• Multiples fuentes en mismo documento
• Alineacion (izquierda, centro, derecha)
• Word wrap automatico
• Interlineado configurable
• Texto multilinea

Fase 3 - Imagenes (PENDIENTE)

• JPEG embebido
• PNG embebido (con alpha)
• Escalado y posicionamiento
• Aspect ratio preservation

Fase 4 - Utilidades (PENDIENTE)

• Helper para tablas
• Numeracion de paginas
• Headers/footers automaticos
• Margenes de pagina
• Links/URLs

Fase 5 - Avanzado (FUTURO)

• Fuentes TTF embebidas
• Compresion de streams
• Metadatos documento (autor, titulo)
• Bookmarks/outline
• Forms (campos rellenables)

---

Arquitectura

Estructura de Archivos

zpdf/
├── CLAUDE.md              # Este archivo - estado del proyecto
├── build.zig              # Sistema de build
├── src/
│   └── root.zig           # Libreria principal (todo en uno por ahora)
└── examples/
    ├── hello.zig          # Ejemplo basico
    └── invoice.zig        # Factura ejemplo

Formato PDF

Generamos PDF 1.4 (compatible con todos los lectores):

%PDF-1.4
%[binary marker]
1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj
2 0 obj << /Type /Pages /Kids [...] /Count N >> endobj
3 0 obj << /Type /Page ... >> endobj
4 0 obj << /Length ... >> stream ... endstream endobj
xref
0 N
trailer << /Size N /Root 1 0 R >>
startxref
...
%%EOF

Fuentes Type1 Built-in

PDF incluye 14 fuentes estandar que no necesitan embeber:

• Helvetica: helvetica, helvetica_bold, helvetica_oblique, helvetica_bold_oblique
• Times: times_roman, times_bold, times_italic, times_bold_italic
• Courier: courier, courier_bold, courier_oblique, courier_bold_oblique
• Otros: symbol, zapf_dingbats

Tamanos de Pagina

Nombre	Puntos	Milimetros
A4	595 x 842	210 x 297
A3	842 x 1191	297 x 420
A5	420 x 595	148 x 210
Letter	612 x 792	216 x 279
Legal	612 x 1008	216 x 356

---

API Actual

Crear Documento

const pdf = @import("zpdf");

var doc = pdf.Document.init(allocator);
defer doc.deinit();

Agregar Paginas

// Tamano estandar
var page = try doc.addPage(.a4);

// Tamano personalizado (en puntos, 1pt = 1/72 inch)
var page = try doc.addPageCustom(500, 700);

Texto

try page.setFont(.helvetica_bold, 24);
page.setFillColor(pdf.Color{ .r = 0, .g = 0, .b = 255 });
try page.drawText(50, 750, "Titulo");

try page.setFont(.times_roman, 12);
page.setFillColor(pdf.Color.black);
try page.drawText(50, 700, "Texto normal");

Graficos

// Linea
try page.setLineWidth(1);
page.setStrokeColor(pdf.Color.gray);
try page.drawLine(50, 600, 500, 600);

// Rectangulo solo borde
try page.drawRect(50, 500, 200, 100);

// Rectangulo relleno
page.setFillColor(pdf.Color.light_gray);
try page.fillRect(50, 400, 200, 100);

// Rectangulo con borde y relleno
page.setFillColor(pdf.Color{ .r = 200, .g = 220, .b = 255 });
page.setStrokeColor(pdf.Color.blue);
try page.drawFilledRect(50, 300, 200, 100);

Guardar

// A archivo
try doc.saveToFile("documento.pdf");

// A buffer (para enviar por red, etc.)
const data = try doc.render(allocator);
defer allocator.free(data);

Colores Predefinidos

pdf.Color.black       // (0, 0, 0)
pdf.Color.white       // (255, 255, 255)
pdf.Color.red         // (255, 0, 0)
pdf.Color.green       // (0, 255, 0)
pdf.Color.blue        // (0, 0, 255)
pdf.Color.gray        // (128, 128, 128)
pdf.Color.light_gray  // (200, 200, 200)

---

Comandos

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

# Compilar
$ZIG build

# Tests
$ZIG build test

# Ejecutar ejemplos
$ZIG build hello && ./zig-out/bin/hello
$ZIG build invoice && ./zig-out/bin/invoice

---

Equipo y Metodologia

Normas de Trabajo Centralizadas

IMPORTANTE: Todas las normas de trabajo estan en:

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

Archivos clave a leer:

• LAST_UPDATE.md - LEER PRIMERO - Cambios recientes en normas
• NORMAS_TRABAJO_CONSENSUADAS.md - Metodologia fundamental
• QUICK_REFERENCE.md - Cheat sheet rapido

Estandares Zig Open Source (Seccion #24)

• Claridad: Codigo autoexplicativo, nombres descriptivos
• Doc comments: /// en todas las funciones publicas
• Idiomatico: snake_case, error handling explicito
• Sin magia: Preferir codigo explicito sobre abstracciones complejas

Control de Versiones

# Remote
git remote: git@git.reugenio.com:reugenio/zpdf.git

# Branches
main        # Codigo estable

---

Referencias

gofpdf (Referencia principal)

• Repo: https://github.com/go-pdf/fpdf
• Objetivo: Replicar funcionalidad core en Zig

PDF Reference

• PDF 1.4 Spec: https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf

Otros (Referencia)

• pdf-nano (Zig): https://github.com/GregorBudweiser/pdf-nano

---

Historial de Desarrollo

2025-12-08 - v0.1 (Core Funcional)

• Estructura inicial del proyecto
• Document, Page, Color, Font, PageSize types
• Texto con 14 fuentes Type1 standard
• Graficos: lineas, rectangulos (stroke, fill, both)
• Colores RGB
• Serializacion PDF 1.4 correcta
• 6 tests unitarios pasando
• Ejemplos: hello.zig, invoice.zig funcionales

---

Notas de Desarrollo

Proxima Sesion

1. Implementar word wrap automatico para texto largo
2. Agregar helper para tablas (simplificar invoice.zig)
3. Soporte para imagenes JPEG
4. Alineacion de texto (center, right)

Lecciones Aprendidas

• PDF es formato relativamente simple para generacion basica
• Content streams usan operadores PostScript-like
• Coordenadas PDF son desde bottom-left (Y aumenta hacia arriba)
• Las 14 fuentes Type1 estan garantizadas en todos los lectores PDF

Zig 0.15 Notas

• std.ArrayList cambio a std.ArrayListUnmanaged con allocator explicito
• writer() ahora requiere allocator como parametro
• toOwnedSlice() requiere allocator
• deinit() requiere allocator

---

Proyectos Relacionados

Proyecto	Descripcion	Repo
zcatui	TUI library (ratatui-style)	git.reugenio.com/reugenio/zcatui
zsqlite	SQLite wrapper	git.reugenio.com/reugenio/zsqlite
zpdf	PDF generator (este)	git.reugenio.com/reugenio/zpdf
service-monitor	Monitor de servicios	git.reugenio.com/reugenio/service-monitor

---

© zpdf - Generador PDF para Zig 2025-12-08 - En desarrollo activo