fullbleed-official

<!-- SPDX-License-Identifier: MIT -->
# Fullbleed PDF Engine

**Create PDFs from Python, HTML, and CSS. One install. MIT licensed.**

Build invoices, reports, statements, and variable-data print jobs with a deterministic Rust engine and a Python API. The wheel includes the rendering engine, fonts, and CLI, with no required third-party Python packages or system PDF stack.

[Try in your browser](https://docs.fullbleed.dev/playground/) · [Documentation](https://docs.fullbleed.dev/) · [Examples](https://docs.fullbleed.dev/examples/) · [PyPI](https://pypi.org/project/fullbleed/) · [Release notes](https://github.com/fullbleed-engine/fullbleed-official/releases) · [MIT license](LICENSE)

<p>
  <a href="https://docs.fullbleed.dev/assets/showcase/invoice.pdf"><img src="https://docs.fullbleed.dev/assets/showcase/invoice-1.png" width="48%" alt="Northstar Studio invoice rendered by Fullbleed, with serif typography and forest-green tables"></a>
  <a href="https://docs.fullbleed.dev/assets/showcase/report.pdf"><img src="https://docs.fullbleed.dev/assets/showcase/report-1.png" width="48%" alt="Common Ground community report rendered by Fullbleed, with a vector landscape illustration and editorial layout"></a>
</p>

Actual Fullbleed output. Open either preview for its PDF, or [explore all four designs with complete HTML/CSS, data, and licensed fonts](https://docs.fullbleed.dev/examples/).

## Your first PDF

Start in the [HTML/CSS playground](https://docs.fullbleed.dev/playground/) to edit a designed invoice or report and download a real PDF. It runs locally in your browser with no account or document upload. You can also use the [Python notebook in Colab](https://colab.research.google.com/github/fullbleed-engine/fullbleed-official/blob/master/examples/notebooks/first_invoice.ipynb), or start with a local script:

Python 3.10–3.14 on Windows, macOS, or Linux:

```bash
python -m pip install fullbleed
```

Save this as `hello.py`, then run `python hello.py`:

```python
from pathlib import Path
import fullbleed

html = "<h1>Invoice INV-1042</h1><p>Consulting: USD 1,200.00</p>"
css = "@page { size: A4; margin: 20mm; } h1 { color: #175c52; }"
pdf = fullbleed.PdfEngine().render_pdf(html, css)
Path("invoice.pdf").write_bytes(pdf)
```

Open `invoice.pdf`. The [quickstart](https://docs.fullbleed.dev/getting-started/quickstart/) adds fonts, previews, and a complete project. The runnable source is in [`examples/quickstart/hello.py`](examples/quickstart/hello.py).

**Using Rust?** Start with the [native Rust quickstart](https://docs.fullbleed.dev/getting-started/rust/). The [`fullbleed` crate](https://crates.io/crates/fullbleed) exposes `FullBleed::builder()` and `render_to_buffer(...)`, with no Python requirement. The guide includes runnable invoice and report examples with explicit fonts and PNG previews, plus the [Rust API reference](https://docs.rs/fullbleed/2.5.0/fullbleed/).

## Choose your starting point

| You want to build | Start here |
| --- | --- |
| Distinctive invoices, reports, notices, and statements | [Designed showcase with fonts and source](examples/design_showcase) |
| A native Rust application | [Rust quickstart and runnable examples](https://docs.fullbleed.dev/getting-started/rust/) |
| An invoice from JSON | [Complete, checked example](examples/agent_workflows) |
| Automatic rebuilds while editing HTML/CSS (2.5.0+) | [Watch-mode invoice example](examples/render_watch) |
| A PDF download in FastAPI, Flask, or Django | [Runnable web app examples](examples/web_frameworks) |
| A styled invoice from CSV | [Acme invoice project](examples/acme_invoice) |
| A report that flows across pages | [Business report example](examples/agent_workflows) |
| Tagged output with accessibility checks | [Accessibility workflow](docs/ui-accessibility.md) |
| Many documents from one template | [Fixed and reflowing variable-data examples](examples/agent_workflows) |
| Print profiles and PDF/VT record hierarchies | [Print output and verification scope](docs/pdf-vt.md) |
| A coding-agent or MCP integration | [Agent setup](#agent-discovery-and-integrations) |

[See generated PDFs and their source →](https://docs.fullbleed.dev/examples/)

## Why use Fullbleed?

- **Simple deployment:** prebuilt wheels for 15 platform targets, with no browser or system-font installation needed for the bundled workflow.
- **Repeatable documents:** explicit assets and metadata, deterministic rendering, and SHA-256 reproducibility checks.
- **Document-focused layout:** pagination, headers and footers, tables, template overlays, and per-page data.
- **Volume workflows:** compile a template once, then bind fixed or reflowing records. [Measured workloads and limits](docs/performance-pass-2026-08-04.md).
- **Inspectable output:** PDF inspection, PNG previews, structured diagnostics, and profile verification tooling.

Fullbleed uses static HTML/CSS as a document layout language. Check the [CSS coverage and remaining gaps](docs/css-coverage.md) for your templates. Use a browser when JavaScript or live website behavior is part of the required result.

Profile selection alone does not establish standards conformance. The [release evidence](docs/release/2.4.0-validation-report.md) records the checks performed and their limits.

## Get help and contribute

Ask usage questions and share documents in [Discussions](https://github.com/fullbleed-engine/fullbleed-official/discussions). For a reproducible bug or feature proposal, [open an issue](https://github.com/fullbleed-engine/fullbleed-official/issues/new/choose). The [contributor guide](CONTRIBUTING.md) covers local setup, tests, and where to make changes.

## Agent discovery and integrations

An agent does not need release-specific Fullbleed knowledge. The installed binary generates one canonical contract containing its actual version, selection boundary, capabilities, parser-derived CLI surface, result schemas, PDF profiles, examples, limitations, Agent Skill metadata, MCP tools, and acceptance tasks:

```bash
fullbleed agent-manifest --json
# Equivalent canonical form:
fullbleed agent-contract --format json
```

The committed [`fullbleed-agent-contract.json`](fullbleed-agent-contract.json), [`cli_schema.md`](cli_schema.md), and [`llms.txt`](llms.txt) are generated from the built wheel. CI rejects version, command, schema, profile, or capability drift. Runtime introspection remains authoritative.

The first-party, versionless [`skills/fullbleed/SKILL.md`](skills/fullbleed/SKILL.md) teaches tool selection and the render/preview/diagnose/verify loop without duplicating the manual. It is bundled in the wheel and can be exported into any absent or empty agent-skill directory:

```bash
fullbleed agent skill-path --json
fullbleed agent export-skill .agents/skills/fullbleed --json
```

You can also [install the Skill directly from a pinned GitHub release](https://docs.fullbleed.dev/guides/ai-agents/#from-github) with `gh skill`. The guide shows how to check its source and version; the Python package supplies the rendering engine.

For tool-calling agents, install the separately versioned adapter so the core package remains dependency-free:

```bash
python -m pip install fullbleed-mcp
fullbleed-mcp --root .
```

The stdio server confines document paths to the selected workspace and delegates every engine operation to the installed Fullbleed runtime. It exposes semantic discovery, project creation, render/preview, inspect, verify, assets, and fixed/reflow compiled VDP tools. The dependency-free core also provides `fullbleed mcp --root .`.

Use Fullbleed when the requested artifact is a deterministic print document built from structured content. Use a browser when the requested artifact is a screenshot or interactive state of an arbitrary live website. Use a general PDF editor when existing page content itself must be rewritten.

Cold-agent testing is available through `fullbleed agent-acceptance`; compact copyable workflows live in [`examples/agent_workflows`](examples/agent_workflows), and the approach-neutral benchmark scaffold lives in [`agentdocbench`](agentdocbench).


This README is the canonical usage guide for:

- `fullbleed` CLI (human workflows + machine/agent automation)
- `fullbleed` Python bindings (`PdfEngine`, `AssetBundle`, batch APIs)

Additional focused references are in `docs/`:

- `docs/install-non-technical.md` (step-by-step setup for non-technical users)
- `docs/css-coverage.md` (validated CSS coverage, parity status, and active gaps)
- `docs/README.md`
- `docs/engine.md`
- `docs/performance-architecture.md`
- `docs/performance-pass-2026-08-04.md`
- `docs/python-api.md`
- `docs/ui-accessibility.md`
- `docs/cli.md`
- `docs/pdf-templates.md`

## What You Get

- No headless browser requirement for PDF generation.
- Deterministic render pipeline with optional SHA256 output hashing.
- Reproducibility workflow via `--repro-record` and `--repro-check`.
- PDF `1.7` as the production-stable default target.
- Rust-native PDF template composition for VDP/transactional overlays.
- Native Rust image emission for overlay and finalized compose outputs (`--emit-image`) without external PDF raster runtime dependencies.
- Feature-driven page-to-template binding with per-page deterministic compose plans.
- Structured JSON result schemas for CI and AI agents.
- Offline-first asset model with explicit remote opt-in.
- Remote project template registry workflows (`new list`, `new search`, `new remote`).
- Python-first extension surface for hackability and custom workflows.
- Python render calls release the GIL while Rust rendering executes.
- Ordered standard-library worker pools for batch rendering and selected internal workloads.
- A deliberately small, license-audited Rust dependency graph and no required third-party Python
  runtime or build packages.

## Concurrency Model

- Python binding render methods release the GIL during Rust execution through the Stable ABI bridge.
- Parallel batch APIs use Fullbleed's ordered standard-li