Fullbleed PDF Engine

Fullbleed PDF Engine is a deterministic, self-contained document-generation runtime for Python and Rust. It turns structured data plus static HTML/CSS into reports, invoices, statements, letters, forms, certificates, accessible PDFs, print-ready documents, and high-volume compiled VDP output—without a browser or system PDF stack.

It is designed for human developers, automation, and AI agents alike: the installed runtime exposes its exact version, capabilities, commands, schemas, compliance profiles, examples, limitations, and tool-selection boundary as a generated machine contract.

License: MIT.

• Install: pip install fullbleed
• Try: fullbleed init . && python report.py
• Discover: fullbleed agent-contract --format json
• Outputs: output/report.pdf
• Deterministic + reproducible (--repro-record / --repro-check)
• Agent-safe JSON schemas (--json-only, --schema)

Positioning

Fullbleed is a deterministic, offline-first document rendering engine for structured print-document and transactional/VDP pipelines (not a browser, not a hosted web-to-print SaaS, and not a general editor for arbitrary existing PDF content).

HTML and CSS are used as a familiar DSL for layout, styling, and data placement in transactional documents.

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:

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

The committed fullbleed-agent-contract.json, cli_schema.md, and 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 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:

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

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

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, and the approach-neutral benchmark scaffold lives in 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-library worker pool (render_pdf_batch_parallel(...) and parallel-to-file variants).
• The same bounded worker implementation serves selected internal hotspots such as table layout and JIT paint paths.
• Do not assume every single-document render path will fully saturate all cores end-to-end.

Performance in 2.2

Fullbleed 2.2 retains exact TrueType glyph subsetting and adds compiled fixed-geometry variable-data binding. Across the five independent benchmark fixtures, PDFs are 95.5-97.3% smaller and ordinary warm rendering is 2.90x faster by geometric mean than released 2.0.0.

The new compile-once API freezes an immutable Q32.32 display document and can link it repeatedly without rerunning HTML parsing, selector matching, layout, pagination, or command planning. For identical untagged copies in one ordered PDF, CompiledDocument.render_pdf_batch(...) shares each source page's content stream across the copied page dictionaries. The measured 20-copy lane is 200.7x faster per page by geometric mean than the released 2.0.0 warm renderer; a 1,000-page stress run sustained 304,479-666,622 pages/s.

The 2.2 compiler includes a genuine fixed-geometry variable-data lane. A compiled invoice with six bound fields rendered 100,000 distinct records in a five-run median of 283.807 ms to memory (352,352 pages/s) and 295.999 ms directly to a flushed 88.1 MB PDF (337,839 pages/s). Including the one-time 4.168 ms compile gives 333,147 direct-file pages/s. The harness verified all 100,000 unique invoice IDs in page order, exact page count, resolved markers, deterministic bytes, and equal buffer/file SHA-256. Reproduce it with:

python tools/benchmark_fullbleed_vdp.py --records 100000 --repeats 5

Fixed-geometry slots may remain inside immutable page-space transforms and clips. The compiler captures that active coordinate-state program once and replays it in each compact record overlay; it does not rerun layout or clone the complete page display list.

Base-14/WinAnsi slot paint keeps the measured byte-patch linker. Registered embedded fonts use a command-level overlay program so each bound value is shaped and included in the font subset while the compiled layout, pagination, and static page stream remain shared. The throughput figures above describe the Base-14 fast lane; they are not claims for registered-font shaping.

The fixed-copy result remains scoped to identical content; the variable-data result is scoped to paint-only text whose geometry does not reflow. Neither is a claim that arbitrary new HTML or size-changing records render 200x faster. See docs/performance-pass-2026-08-04.md for measurements and docs/performance-architecture.md for the packed vector IR, typed-binding, virtual-linker, and shader roadmap.

Fullbleed 2.2.5 hardens the third compiler lane introduced in 2.2.4 for size-changing records: CompiledDocument.render_pdf_reflow_bindings(...). It parses and recovers the template DOM once and compiles encountered structural flow variants into guarded fixed-point display programs. Matching records bind directly into those programs; workers execute pre-shaped text/TJ paint slots, cached static PDF page segments, page-local Deflate, and one ordered linker. Explicit trusted structural slots use data-fb-bind-html="slot". A value that no compiled variant can safely place runs ordinary fixed-point layout once to add another variant.

On the independent 1,000-distinct-record case study, the 29-sample hot direct-file median was 216.160 ms: 4,626 records/s and 8,096 pages/s. The 168.995 ms best sample reached 5,917 records/s and 10,355 pages/s. It produced the exact 1,750-page 500/300/150/50 reflow distribution and verified all 24,900 markers. The throughput-tuned 6,870,320-byte PDF was deterministic across all samples. With the compact compression setting, compiled output was also byte-for-byte identical to ordinary rendering: 5,298,961 bytes and SHA-256 bb3c441313a08fb00d3bd15f23a567981f3bbbd550908e3a9fe7a07ca5d7f138. This is a hot compiled-variant result, not a claim for previously unseen structure. The first variant-discovery render measured 0.509 s (3,437 pages/s), and the fully cold job including setup, bindings, compilation, discovery, and write measured 0.588 s (2,975 pages/s). The independently observed hot-median speedup over the ordinary path was 43.8x.

Install

New to Python or setting up on a fresh machine? Start with docs/install-non-technical.md.

python -m pip install fullbleed

From a local wheel:

python -m pip install C:\path\to\fullbleed-2.3.1-cp310-abi3-win_amd64.whl

From a source checkout with Rust installed, no Python build package is needed:

python -m pip install --no-build-isolation --no-deps --editable .

To create deterministic release artifacts directly:

python build_backend/fullbleed_build_backend.py wheel --out dist
python build_backend/fullbleed_build_backend.py sdist --out dist

Platform artifact policy:

• Linux wheels cover manylinux2014 on x86-64, x86, ARM64, ARMv7, s390x, and ppc64le, plus musllinux_1_2 on x86-64, x86, ARM64, and ARMv7.
• Windows wheels cover x86-64, x86, and ARM64; macOS wheels cover Intel and Apple silicon.
• The CPython stable ABI allows each platform wheel to support Python 3.10 through 3.14.
• CI installs and exercises every built wheel on its target architecture, using native runners or QEMU as appropriate. The x86-64 manylinux wheel is additionally tested on every supported Python version before publication.

Verify command surface:

fullbleed --help
fullbleed capabilities --json
fullbleed doctor --json

60-Second Quick Start (Project Happy Path)

Initialize project scaffold:

fullbleed init .

fullbleed init now vendors Bootstrap (5.0.0) into vendor/css/bootstrap.min.css, vendors Bootstrap Icons (1.11.3) into vendor/icons/bootstrap-icons.svg, vendors inter into vendor/fonts/Inter-Variable.ttf, writes license notices (vendor/css/LICENSE.bootstrap.txt, vendor/icons/LICENSE.bootstrap-icons.txt, vendor/fonts/LICENSE.inter.txt), and seeds assets.lock.json with pinned hashes. The scaffolded report.py also runs a component mount smoke validation before main render and writes output/component_mount_validation.json (fails fast on missing glyphs, actual pagination overflow, or CSS miss signals). On current engines, render-time pagination is authoritative for overflow; conservative JIT placement bounds remain the compatibility fallback for older engines. Scaffolded components now include components/primitives.py with reusable layout/content helpers (Stack, Row, Text, table/list helpers, key/value rows, etc.). Each scaffolded project also includes SCAFFOLDING.md, which should be your first read before restructuring components. It also includes AGENTS.md, which preserves the installed-runtime-first document workflow across future coding-agent sessions without making other document tools categorically forbidden.

Install additional project assets (defaults to ./vendor/... in project context):

fullbleed assets install inter --json

Bootstrap baseline note:

• We target Bootstrap (5.0.0) as the default styling baseline for project workflows.
• Re-run fullbleed assets install bootstrap --json only if you want to explicitly refresh/bootstrap-manage outside init.

Render using the scaffolded component pipeline:

python report.py

Expected artifacts from scaffolded report.py:

• output/report.pdf
• output/report_page1.png (or equivalent page preview from engine image APIs)
• output/component_mount_validation.json
• output/css_layers.json

Canonical static PDF reference:

python examples/canonical_reference/report.py

examples/canonical_reference/ is the exhaustive scaffold-shaped reference for component composition, layered CSS, bundled fonts/SVG, inline SVG, raster data URIs, linked and standalone HTML artifacts, PDF output, PNG previews, and validation reports.

Project Bootstrap Templates (fullbleed new)

Use local starters:

fullbleed new local invoice ./my-invoice
fullbleed new local statement ./my-statement
fullbleed new local accessible ./my-accessible-doc
fullbleed new local reference ./my-reference-doc

Discover remote starters from registry:

fullbleed new list --json
fullbleed new search i9 --tag vdp --json
fullbleed new remote i9-stamped-vdp ./i9-job --json

fullbleed new local accessible is the verbose accessibility-first starter and demonstrates the fullbleed.accessibility runtime surface (engine verifier, PMR, PDF/UA-targeted seed checks, and non-visual trace artifacts). fullbleed new local reference vendors the canonical static PDF reference shape as a scaffolded project with component layers, assets, PDF/PNG outputs, page data, and validation reports.

Optional registry override (for private/canary registries):

fullbleed new list --registry https://example.com/manifest.json --json

or:

set FULLBLEED_TEMPLATE_REGISTRY=https://example.com/manifest.json
fullbleed new search statement --json

Scaffold-First Workflow (Recommended)

fullbleed init is designed for component-first authoring rather than a single large HTML template.

Typical scaffold layout:

.
|-- SCAFFOLDING.md
|-- COMPLIANCE.md
|-- report.py
|-- components/
|   |-- fb_ui.py
|   |-- primitives.py
|   |-- header.py
|   |-- body.py
|   |-- footer.py
|   `-- styles/
|       |-- primitives.css
|       |-- header.css
|       |-- body.css
|       `-- footer.css
|-- styles/
|   |-- tokens.css
|   `-- report.css
|-- vendor/
|   |-- css/
|   |-- fonts/
|   `-- icons/
`-- output/

Best-practice authoring model:

1. Read SCAFFOLDING.md first for project conventions.
2. Keep composition and data loading in report.py.
3. Keep reusable component building blocks in components/primitives.py.
4. Keep section markup in components/header.py, components/body.py, components/footer.py.
5. Keep component-local styles in components/styles/*.css.
6. Keep page tokens/composition styles in styles/tokens.css and styles/report.css.

Recommended CSS layer order:

1. styles/tokens.css
2. components/styles/primitives.css
3. components/styles/header.css
4. components/styles/body.css
5. components/styles/footer.css
6. styles/report.css

Recommended iteration loop:

1. Edit data loading + component props in report.py.
2. Edit component markup in components/*.py.
3. Edit styles in components/styles/*.css and styles/*.css.
4. Run python report.py.
5. Review output/report_page1.png, output/component_mount_validation.json, and output/css_layers.json.

Optional scaffold diagnostics:

• FULLBLEED_DEBUG=1 to emit JIT traces.
• FULLBLEED_PERF=1 to emit perf traces.
• FULLBLEED_EMIT_PAGE_DATA=1 to persist page data JSON.
• FULLBLEED_IMAGE_DPI=144 (or higher) for preview resolution.
• FULLBLEED_VALIDATE_STRICT=1 for stricter validation gates in CI.

One-off Quick Render (No Project Scaffold)

Render inline HTML/CSS with reproducibility artifacts:

fullbleed --json render \
  --html-str "<html><body><h1>Hello</h1></body></html>" \
  --css-str "body{font-family:sans-serif}" \
  --emit-manifest build/render.manifest.json \
  --emit-jit build/render.jit.jsonl \
  --emit-perf build/render.perf.jsonl \
  --deterministic-hash build/render.sha256 \
  --repro-record build/render.repro.json \
  --out output/hello.pdf

--deterministic-hash writes the output PDF SHA-256 by default; when --emit-image is enabled, it writes an artifact-set digest (fullbleed.artifact_digest.v1) over PDF SHA-256 plus ordered page-image SHA-256 hashes. JSON outputs expose outputs.deterministic_hash_mode (pdf_only or artifact_set_v1), with outputs.artifact_sha256 and outputs.image_sha256 when images are emitted.

Re-run and enforce reproducibility against a stored record:

fullbleed --json render \
  --html templates/report.html \
  --css templates/report.css \
  --repro-check build/render.repro.json \
  --out output/report.rerun.pdf

Generate PNG page artifacts from an existing validation render:

fullbleed --json verify \
  --html templates/report.html \
  --css templates/report.css \
  --emit-pdf output/report.verify.pdf \
  --emit-image output/report_verify_pages \
  --image-dpi 200

Compile-only plan (no render):

fullbleed --json plan \
  --html templates/report.html \
  --css templates/report.css

Template compose planning (no finalize write):

fullbleed --json plan \
  --html templates/overlay.html \
  --css templates/overlay.css \
  --template-binding config/template_binding.json \
  --templates config/template_catalog.json \
  --emit-compose-plan output/compose_plan.json

PDF Template Composition (VDP / Transactional)

When overlaying variable data onto a source PDF, use the built-in Rust template compose path.

Minimal CLI auto-compose flow:

fullbleed --json render \
  --html templates/overlay.html \
  --css templates/overlay.css \
  --asset templates/source.pdf --asset-kind pdf --asset-name source-template \
  --template-binding config/template_binding.json \
  --templates config/template_catalog.json \
  --out output/composed.pdf

Compose image semantics:

• In template auto-compose mode, --emit-image PNGs are rasterized from finalized composed pages and report outputs.image_mode=composed_pdf.
• In non-compose render/verify runs, --emit-image reports outputs.image_mode=overlay_document.

Minimal template_binding example:

{
  "default_template_id": "source-template",
  "feature_prefix": "fb.feature.",
  "by_feature": {
    "front": "source-template",
    "back_blank": "source-template"
  }
}

Python API compose flow:

import fullbleed

engine = fullbleed.PdfEngine(template_binding=binding_spec)
overlay_bytes, _page_data, _bindings = engine.render_pdf_with_page_data_and_template_bindings(html, css)
open("output/overlay.pdf", "wb").write(overlay_bytes)
plan_result = engine.plan_template_compose(
    html,
    css,
    [("source-template", "templates/source.pdf")],
    0.0,
    0.0,
)
plan = [
    (
        row["template_id"],
        row["template_page"],
        row["overlay_page"],
        row["dx"],
        row["dy"],
    )
    for row in plan_result["plan"]
]
fullbleed.finalize_compose_pdf(
    [("source-template", "templates/source.pdf")],
    plan,
    "output/overlay.pdf",
    "output/composed.pdf",
    annotation_mode="link_only",  # optional: link_only | none | carry_widgets
)

See docs/pdf-templates.md and examples/template-flagging-smoke/ for full production examples.

CLI Command Map

Command	Purpose	JSON Schema
render	Render HTML/CSS to PDF with optional PNG page artifacts	fullbleed.render_result.v1
verify	Validation render path with optional PDF and PNG emits	fullbleed.verify_result.v1
plan	Compile/normalize inputs into manifest + warnings	fullbleed.plan_result.v1
run	Render using Python module/file engine factory	fullbleed.run_result.v1
inspect pdf	Inspect PDF metadata and composition compatibility	fullbleed.inspect_pdf.v1
inspect pdf-batch	Inspect multiple PDFs with per-file status	fullbleed.inspect_pdf_batch.v1
inspect templates	Inspect template catalog metadata/compatibility	fullbleed.inspect_templates.v1
compliance	License/compliance report for legal/procurement	fullbleed.compliance.v1
debug-perf	Summarize perf JSONL logs	fullbleed.debug_perf.v1
debug-jit	Filter/inspect JIT JSONL logs	fullbleed.debug_jit.v1
doctor	Runtime capability and health checks	fullbleed.doctor.v1
capabilities	Machine-readable command/engine capabilities	fullbleed.capabilities.v1
assets list	Installed and optional remote packages	fullbleed.assets_list.v1
assets info	Package details + hashes/sizes	fullbleed.assets_info.v1
assets install	Install builtin/remote package	fullbleed.assets_install.v1
assets verify	Validate package and optional lock constraints	fullbleed.assets_verify.v1
assets lock	Write/update assets.lock.json	fullbleed.assets_lock.v1
cache dir	Cache location	fullbleed.cache_dir.v1
cache prune	Remove old cached packages	fullbleed.cache_prune.v1
init	Initialize project scaffold	fullbleed.init.v1
new	Create starter template files or query/install remote templates	fullbleed.new_template.v1, fullbleed.new_list.v1, fullbleed.new_search.v1, fullbleed.new_remote.v1

Schema discovery for any command/subcommand:

fullbleed --schema render
fullbleed --schema assets verify
fullbleed --schema inspect pdf
fullbleed --schema inspect templates

CLI Flags That Matter Most

Global machine flags:

• --json: structured result payload to stdout
• --json-only: implies --json and --no-prompts
• --schema: emit schema definition and exit
• --no-prompts: disable interactive prompts
• --config: load defaults from a config file
• --log-level error|warn|info|debug: control CLI log verbosity
• --no-color: disable ANSI color output
• --version: print CLI version and exit

Render/verify/plan key flags:

• Inputs: --html, --html-str, --css, --css-str --html accepts .svg files for direct SVG-document rendering; --html-str accepts inline SVG markup.
• Page setup: --page-size, --page-width, --page-height, --margin, --page-margins
• Engine toggles: --reuse-xobjects, --svg-form-xobjects, --svg-raster-fallback, --shape-text, --unicode-support, --unicode-metrics
• PDF/compliance: --pdf-version, --pdf-profile, --color-space, --document-lang, --document-title Stable default is --pdf-version 1.7 for shipping workflows. Profile targets: none, pdfa1a, pdfa1b, pdfa2a, pdfa2b, pdfa2u, pdfa3a, pdfa3b, pdfa3u, pdfa4, pdfa4e, pdfa4f, pdfx4, pdfua1, pdfua2, pdfvt1, wtpdf1r, wtpdf1a, tagged. Aliases: a, ua, vt, wt1r, wt1a, pdf/a, pdf/ua, pdf/vt. Output intent metadata (--output-intent-identifier|--output-intent-info|--output-intent-components) requires --output-intent-icc. Run `python tools/validate_pdf_pro