printwell-cli 0.1.10

# printwell

[![npm](https://img.shields.io/npm/v/printwell)](https://www.npmjs.com/package/printwell)
[![crates.io](https://img.shields.io/crates/v/printwell)](https://crates.io/crates/printwell)
[![PyPI](https://img.shields.io/pypi/v/printwell)](https://pypi.org/project/printwell/)
[![docs](https://img.shields.io/badge/docs-printwell-blue)](https://printwell-dev.github.io/core/)

> **Early Development** - This project is in active early development. APIs may change, and some features are incomplete. Some commercial features may become free in future releases. Feedback and contributions welcome!

High-fidelity HTML to PDF conversion using Chromium's rendering engine.

## Features

- **Rendering**: Full HTML5/CSS3 support via Chromium's Blink engine
- **Large Documents**: Automatic chunking for documents >50MB with parallel rendering
- **Watermarks**: Text and image overlays with positioning and opacity control
- **Bookmarks**: Table of contents and navigation structure
- **Annotations**: Highlights, sticky notes, and geometric shapes

## Crates

| Crate | Description |
|-------|-------------|
| [`printwell`](https://crates.io/crates/printwell) | High-level API |
| [`printwell-core`](https://crates.io/crates/printwell-core) | Rendering engine |
| [`printwell-pdf`](https://crates.io/crates/printwell-pdf) | PDF manipulation |
| [`printwell-sys`](https://crates.io/crates/printwell-sys) | FFI bindings |
| [`printwell-cli`](https://crates.io/crates/printwell-cli) | Command-line tool |

## Quick Start

```rust
use printwell::{Converter, PdfOptions, RenderOptions, PageSize};

#[tokio::main]
async fn main() -> printwell::Result<()> {
    let converter = Converter::new()?;

    let pdf = converter.html_to_pdf(
        "<h1>Hello, World!</h1>",
        &RenderOptions::default(),
        &PdfOptions::builder()
            .page_size(PageSize::A4)
            .print_background(true)
            .build(),
    ).await?;

    pdf.write_to_file("output.pdf")?;
    Ok(())
}
```

## CLI Usage

```bash
# Convert HTML file
printwell convert input.html -o output.pdf

# Convert URL
printwell convert https://example.com -o output.pdf

# Convert with custom page size and margins
printwell convert input.html -o output.pdf --page-size Letter --margin 20mm

# Add watermark
printwell watermark input.pdf -o output.pdf --text "CONFIDENTIAL" --opacity 0.3

# Add bookmarks
printwell bookmarks input.pdf -o output.pdf --add "Chapter 1:1" --add "Chapter 2:5"

# Add annotations
printwell annotate input.pdf -o output.pdf --highlight 1:100:700:200:20

# Batch convert multiple files
printwell convert-batch *.html -o output_dir/ --workers 4
```

## Bindings

### Node.js ([npm](https://www.npmjs.com/package/printwell))

```typescript
import { Converter, htmlToPdf } from 'printwell';

// Simple conversion
const result = await htmlToPdf('<h1>Hello, World!</h1>');
result.writeToFile('output.pdf');

// With options
const converter = new Converter();
const pdf = await converter.htmlToPdf(html, {}, {
    pageSize: 'A4',
    printBackground: true,
});
```

### Python ([PyPI](https://pypi.org/project/printwell/))

```python
from printwell import Converter, html_to_pdf

# Simple conversion
result = html_to_pdf('<h1>Hello, World!</h1>')
result.write_to_file('output.pdf')

# With options
converter = Converter()
pdf = converter.html_to_pdf(html, pdf_options=PdfOptions(
    page_size=PageSize.A4,
    print_background=True,
))
```

## Requirements

- **Rust**: 1.92.0 or later (MSRV)
- **Docker**: Required for building the native library

## Architecture

Printwell uses a two-layer architecture:

1. **Native library** (`libprintwell_native.so`) - Shared library with C++ code + Chromium (blink, skia, pdfium), built with ThinLTO
2. **Rust layer** - High-level API that links against the native library dynamically

The native library (~50MB) is pre-built and stored in the repo, so most contributors don't need to build Chromium.

> **Note:** We are working on a Chromium CI workflow to build and distribute the native library separately from the repo. This will reduce clone sizes and improve the contributor experience.

## Building

### For Contributors (without Chromium)

Contributors can build and test without cloning/building Chromium:

```bash
# Build CLI (links against pre-built libprintwell_native.so)
cargo build -p printwell-cli --release

# Build bindings
cargo xtask bindings node --release
cargo xtask bindings python --release

# Run tests
cargo xtask bindings test
```

### For Core Developers (with Chromium)

Core developers who need to modify C++ code or update Chromium:

```bash
# Setup build environment (one-time)
cargo xtask init

# Fetch Chromium source (~30GB)
cargo xtask chromium fetch

# Sync Chromium dependencies
cargo xtask chromium sync

# Build native library (libprintwell_native.so)
cargo xtask build --release

# After C++ changes, commit the updated native library:
git add native/linux-x64/libprintwell_native.so
git commit -m "Update pre-built native library"
```

### Testing

```bash
# Run binding tests
cargo xtask bindings test

# Run end-to-end tests
cargo xtask e2e

# Run lints
cargo xtask lint
```

## License

AGPL-3.0 - See [LICENSE](LICENSE) for details.