# zpdf - Generador PDF para Zig

> **Fecha creación**: 2025-12-08
> **Versión Zig**: 0.15.2
> **Estado**: En desarrollo inicial

## Descripción del Proyecto

Librería pura Zig para generación de documentos PDF. Sin dependencias externas, compila a un binario único.

**Filosofía**:
- Zero dependencias (100% Zig)
- API simple y directa
- Enfocado en generación de facturas/documentos comerciales
- Soporte para texto, tablas, imágenes y formas básicas

## Arquitectura

```
zpdf/
├── CLAUDE.md           # Este archivo
├── build.zig           # Sistema de build
├── src/
│   ├── root.zig        # Exports públicos
│   ├── document.zig    # Documento PDF principal
│   ├── page.zig        # Páginas
│   ├── stream.zig      # Content streams
│   ├── text.zig        # Renderizado de texto
│   ├── graphics.zig    # Líneas, rectángulos, etc.
│   ├── image.zig       # Imágenes embebidas
│   ├── fonts.zig       # Fuentes Type1 básicas
│   └── writer.zig      # Serialización PDF
└── examples/
    ├── hello.zig       # PDF mínimo
    └── invoice.zig     # Factura ejemplo
```

## Formato PDF

Usamos PDF 1.4 (compatible con todos los lectores). Estructura básica:

```
%PDF-1.4
1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj
2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj
3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R >> endobj
4 0 obj << /Length ... >> stream ... endstream endobj
xref
0 5
0000000000 65535 f
...
trailer << /Size 5 /Root 1 0 R >>
startxref
...
%%EOF
```

## API Objetivo

```zig
const std = @import("std");
const pdf = @import("zpdf");

pub fn main() !void {
    var allocator = std.heap.page_allocator;

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

    var page = try doc.addPage(.a4);

    // Texto
    try page.setFont(.helvetica_bold, 24);
    try page.drawText(50, 750, "Factura #001");

    try page.setFont(.helvetica, 12);
    try page.drawText(50, 700, "Cliente: Empresa S.L.");

    // Línea
    try page.setLineWidth(0.5);
    try page.drawLine(50, 690, 550, 690);

    // Rectángulo
    try page.setFillColor(.{ .r = 240, .g = 240, .b = 240 });
    try page.fillRect(50, 600, 500, 20);

    // Tabla (helper)
    try page.drawTable(.{
        .x = 50,
        .y = 580,
        .columns = &.{ 200, 100, 100, 100 },
        .headers = &.{ "Descripción", "Cantidad", "Precio", "Total" },
        .rows = &.{
            &.{ "Producto A", "2", "10.00", "20.00" },
            &.{ "Producto B", "1", "25.00", "25.00" },
        },
    });

    // Guardar
    try doc.save("factura.pdf");
}
```

## Funcionalidades Planificadas

### Fase 1 - Core (Actual)
- [ ] Estructura documento PDF 1.4
- [ ] Páginas (A4, Letter, custom)
- [ ] Texto básico (fuentes Type1 built-in)
- [ ] Líneas y rectángulos
- [ ] Serialización correcta

### Fase 2 - Texto Avanzado
- [ ] Múltiples fuentes en mismo documento
- [ ] Colores (RGB, CMYK, grayscale)
- [ ] Alineación (izquierda, centro, derecha)
- [ ] Word wrap automático

### Fase 3 - Imágenes
- [ ] JPEG embebido
- [ ] PNG embebido (con alpha)
- [ ] Escalado y posicionamiento

### Fase 4 - Utilidades
- [ ] Helper para tablas
- [ ] Numeración de páginas
- [ ] Headers/footers

## Fuentes Type1 Built-in

PDF incluye 14 fuentes estándar que no necesitan embeber:
- Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
- Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
- Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
- Symbol, ZapfDingbats

## Tamaños de Página

```zig
pub const PageSize = enum {
    a4,      // 595 x 842 points (210 x 297 mm)
    letter,  // 612 x 792 points (8.5 x 11 inches)
    legal,   // 612 x 1008 points
    a3,      // 842 x 1191 points
    a5,      // 420 x 595 points
};
```

## Referencias

- [PDF Reference 1.4](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf)
- [pdf-nano (Zig)](https://github.com/GregorBudweiser/pdf-nano) - Referencia minimalista

---

## Equipo y Metodología

### Normas de Trabajo

**IMPORTANTE**: Todas las normas de trabajo están en:
```
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/
```

### Control de Versiones

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

# Branches
main        # Código estable
develop     # Desarrollo activo
```

### Zig Path

```bash
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
```

---

## Notas de Desarrollo

*Se irán añadiendo conforme avance el proyecto*