# zcatpdf - Generador PDF para Zig

> **Tipo:** Librería Zig (sin deploy propio)
> **Credenciales:** `teamdocs/INFRASTRUCTURE/CREDENCIALES.md`
> **Cheatsheet:** `teamdocs/CHEATSHEET.md`
> **Version:** v1.0 - RELEASE (FEATURE COMPLETE)
> **Repositorio:** 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 (teamdocs)

**Ubicacion**: `/mnt/cello2/arno/re/recode/teamdocs/`

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

```bash
# 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

```zig
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

```bash
# 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](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf)
- [fpdf2 (Python)](https://github.com/py-pdf/fpdf2) - Inspiracion de la API
- [Zig Documentation](https://ziglang.org/documentation/master/)

---

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

---

## CLAUDE CODE + ZLS (LSP)

Claude Code tiene integración LSP con zls (Zig Language Server).

**Plugin:** `$HOME/.claude/plugins/zls-lsp/`

**Operaciones disponibles:**

| Operación | Uso |
|-----------|-----|
| `goToDefinition` | Navegar a definición de símbolo |
| `findReferences` | Encontrar todas las referencias |
| `hover` | Info de tipo y documentación |
| `documentSymbol` | Símbolos del archivo actual |
| `incomingCalls` | Qué funciones llaman a ésta |

**Documentación:** `teamdocs/INFRASTRUCTURE/ZLS_LSP_CLAUDE_CODE.md`