zcatpdf/CLAUDE.md

zpdf - Generador PDF para Zig

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

zpdf 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

---

Estado Actual - v1.0

Funcionalidades Implementadas

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)	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

Tests y Ejemplos

• 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

---

Arquitectura

zpdf/
├── 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

const zpdf = @import("zpdf");

var doc = zpdf.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

// cell() simple
try page.cell(100, 20, "Hello", zpdf.Border.all, .center, true);

// multiCell con word wrap
try page.multiCell(400, null, texto_largo, zpdf.Border.none, .left, false);

// Table helper
const widths = [_]f32{ 200, 100, 100 };
var table = zpdf.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

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

// 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

// 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

// 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

// 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

// 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, zpdf.QRCode.ErrorCorrection.M);

// Error correction levels:
// .L - Low (7% recovery)
// .M - Medium (15% recovery)
// .Q - Quartile (25% recovery)
// .H - High (30% recovery)

TrueType Fonts

// 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

// 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

// 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

// Numeros de pagina
try zpdf.Pagination.addPageNumbers(&doc, .{
    .format = "Page {PAGE} of {PAGES}",
    .position = .bottom_center,
});

// Header con linea
try zpdf.addHeader(&doc, "Documento", .{
    .draw_line = true,
});

---

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

# 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

---

Roadmap Completado

Fase 1 - Core (COMPLETADO)

• Estructura PDF 1.4
• Paginas multiples
• Texto basico
• Graficos (lineas, rectangulos)
• Colores

Fase 2 - Texto Avanzado (COMPLETADO)

• cell() / cellAdvanced()
• multiCell() con word wrap
• Alineacion
• Bordes

Fase 3 - Imagenes (COMPLETADO)

• JPEG embedding
• image() / imageFit()
• PNG embedding completo

Fase 4 - Utilidades (COMPLETADO)

• Table helper
• Paginacion
• Headers/Footers
• Links visuales

Fase 5 - Links Clickeables (COMPLETADO)

• URL annotations
• Internal page links
• Link annotations en PDF

Fase 6 - PNG + Compresion (COMPLETADO)

• Integracion libdeflate-zig
• PNG parsing completo (RGB, RGBA, Grayscale, Indexed)
• PNG unfiltering (None, Sub, Up, Average, Paeth)
• Soft masks para canal alpha
• FlateDecode para content streams
• Compresion configurable (nivel 0-12)
• Heuristica inteligente (min_size, min_ratio)

Fase 7 - Bookmarks/Outline (COMPLETADO)

• OutlineItem struct
• addBookmark() / addBookmarkAt()
• Outline en sidebar del lector PDF

Fase 8 - Curvas Bezier (COMPLETADO)

• drawBezier() - curvas cubicas
• drawQuadBezier() - curvas cuadraticas
• drawCircle() / fillCircle()
• drawEllipse() / fillEllipse()
• drawArc()

Fase 9 - Transformaciones (COMPLETADO)

• rotate() - rotacion alrededor de punto
• scale() - escala desde punto
• translate() - traslacion
• skew() - deformacion
• transform() - matriz personalizada
• saveState() / restoreState()

Fase 10 - Transparencia (COMPLETADO)

• ExtGState para opacidad
• setFillOpacity()
• setStrokeOpacity()
• setOpacity()

Fase 11 - Gradientes (COMPLETADO)

• LinearGradient (horizontal, vertical, diagonal)
• RadialGradient (circle, ellipse)
• Shading Patterns Type 2 (axial) y Type 3 (radial)
• linearGradientRect()
• radialGradientCircle()
• radialGradientEllipse()

Fase 12 - Barcodes (COMPLETADO)

• Code128 1D barcode (ASCII 0-127)
• Code Sets A, B, C con switching automatico
• QR Code 2D barcode (ISO/IEC 18004)
• Error correction levels (L, M, Q, H)
• drawCode128() / drawCode128WithText()
• drawQRCode()

Fase 13 - TTF Fonts (COMPLETADO)

• TrueType font file parsing
• Font metrics (units_per_em, ascender, descender, etc.)
• Glyph width tables
• Character to glyph mapping (cmap format 0, 4, 6, 12)
• addTtfFontFromFile()
• stringWidth() calculation
• Full TTF embedding for PDF rendering (CIDFont Type 2) - Future

Fase 14 - Security/Encryption (COMPLETADO)

• RC4 stream cipher (40-bit and 128-bit)
• PDF Standard Security Handler
• User/Owner password handling
• Permission flags (print, modify, copy, annotate, etc.)
• MD5-based key derivation
• Object key generation
• Full PDF output integration - Future

Fase 15 - Forms/AcroForms (COMPLETADO)

• TextField struct (name, position, size)
• CheckBox struct
• FieldFlags (readonly, required, multiline, password)
• FormField union type
• toFormField() conversion
• Full PDF AcroForm output integration - Future

Fase 16 - SVG Import (COMPLETADO)

• SvgParser struct
• Basic shapes (rect, circle, ellipse, line)
• Path element with commands
• PathCommand enum (MoveTo, LineTo, CurveTo, etc.)
• Color parsing (fill, stroke)
• toPdfContent() - generates PDF operators
• Text elements - Future
• Transforms - Future

Fase 17 - Templates (COMPLETADO)

• Template struct with named regions
• TemplateRegion (position, size, type)
• RegionType enum (text, image, table, custom)
• FixedContent for repeating elements
• invoiceTemplate() predefined
• letterTemplate() predefined
• template_demo.zig ejemplo

Fase 18 - Markdown Styling (COMPLETADO)

• MarkdownRenderer struct
• SpanStyle (bold, italic, underline, strikethrough)
• TextSpan with style, color, url, font_size
• Inline parsing: bold, italic, both, strike
• Links: text
• Headings: #, ##, ###
• Lists: - bullet, 1. numbered
• fontForStyle() helper
• 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
• 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

/mnt/cello2/arno/re/recode/TEAM_STANDARDS/
git remote: git@git.reugenio.com:reugenio/zpdf.git

---

zpdf - Generador PDF para Zig v1.0 - RELEASE (FEATURE COMPLETE) - 2025-12-09