Skip to content
Back to search

fullbleed-official

Fullbleed PDF Engine - deterministic Python/Rust document generation for reports, invoices, accessible/print-ready PDF, and compiled VDP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fullbleed-engine--fullbleed-official/badge.svg)](/listings/fullbleed-engine--fullbleed-official)

HTML

<a href="/listings/fullbleed-engine--fullbleed-official"><img src="/api/listings/fullbleed-engine--fullbleed-official/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.5.8-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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,714 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- SPDX-License-Identifier: MIT -->
  2. # Fullbleed PDF Engine
  3. [![PyPI](https://img.shields.io/pypi/v/fullbleed)](https://pypi.org/project/fullbleed/)
  4. [![PyPI Downloads](https://img.shields.io/pypi/dm/fullbleed)](https://pypistats.org/packages/fullbleed)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. **Generate PDFs from HTML/CSS in Python, Rust, JavaScript, and C#. MIT licensed.**
  7. Build invoices, reports, statements, and variable-data print jobs with a deterministic Rust engine. Use the native Rust API, the Python package, or the optional JavaScript and .NET integrations. The Python wheel includes the engine, fonts, and CLI with no required third-party Python packages or system PDF stack. The JavaScript package includes the WebAssembly engine and fonts for Node.js and browser workers; the .NET package includes native libraries for in-process rendering.
  8. [Try your own document](https://docs.fullbleed.dev/playground/) · [Documentation](https://docs.fullbleed.dev/) · [Examples](https://docs.fullbleed.dev/examples/) · [PyPI](https://pypi.org/project/fullbleed/) · [crates.io](https://crates.io/crates/fullbleed) · [npm](https://www.npmjs.com/package/fullbleed) · [Release notes](https://github.com/fullbleed-engine/fullbleed-official/releases) · [MIT license](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/LICENSE)
  9. <p>
  10. <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>
  11. <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>
  12. </p>
  13. Actual Fullbleed output. Open either preview for its PDF, or [explore the designed examples with HTML/CSS, data, and font setup](https://docs.fullbleed.dev/examples/).
  14. [Compare both designs in HTML/CSS and Python components](https://docs.fullbleed.dev/guides/showcase-authoring/), with matching page output and runnable source. The component versions use the opt-in 2.6 alpha.
  15. ## Choose your language
  16. | Language | Install | Start building |
  17. | --- | --- | --- |
  18. | Python | `python -m pip install fullbleed` | [Python quickstart](https://docs.fullbleed.dev/getting-started/quickstart/) |
  19. | Rust | `cargo add fullbleed` | [Native Rust quickstart](https://docs.fullbleed.dev/getting-started/rust/) |
  20. | Node.js / TypeScript | `npm install fullbleed` | [Node quickstart](https://docs.fullbleed.dev/getting-started/node/) · [Next.js PDF download](https://docs.fullbleed.dev/guides/nextjs-pdf/) |
  21. | Browser JavaScript | `npm install fullbleed` | [PDF components and JSX](https://docs.fullbleed.dev/guides/javascript-components/) · [React starter](https://docs.fullbleed.dev/guides/react-pdf/) · [HTML/CSS starter](https://docs.fullbleed.dev/guides/browser-pdf/) |
  22. | C# / .NET | `dotnet add package FullBleed.DotNet` | [C# components and styles](https://docs.fullbleed.dev/guides/csharp-components/) · [NuGet quickstart](https://docs.fullbleed.dev/getting-started/dotnet/) |
  23. The language packages release independently. The [Node quickstart](https://docs.fullbleed.dev/getting-started/node/),
  24. [browser guide](https://docs.fullbleed.dev/guides/browser-pdf/) and
  25. [C# quickstart](https://docs.fullbleed.dev/getting-started/dotnet/) record the
  26. tested package and engine versions; downloadable starters pin their dependencies.
  27. JavaScript applications can [export styled or unstyled component HTML](https://docs.fullbleed.dev/guides/javascript-components/#export-html-with-or-without-styles)
  28. and generate PDFs and previews. Import `fullbleed` in Node or `fullbleed/browser`
  29. in a web app. Node applications can use a
  30. [bounded render queue](https://docs.fullbleed.dev/guides/node-render-queue/)
  31. and optional process isolation.
  32. FullBleed.DotNet's managed library targets .NET 8 and works with .NET 8, 9, and 10
  33. applications. It includes C# components, native rendering, compiled bindings and
  34. previews. Its separate CLI adapter requires the Python CLI.
  35. The Python package provides the complete CLI, including compiled variable-data jobs and print profiles; the Rust guide covers the native API.
  36. ## Your first PDF
  37. Start in the [HTML/CSS playground](https://docs.fullbleed.dev/playground/) with a designed invoice or report, or choose **Open local files** to use your own HTML, CSS, images, and fonts. Rendering runs locally in your browser, with no account or document upload.
  38. Download the PDF, or select **Python** or **Node.js** under **Project language** and choose **Download project**. The ZIP includes your source, assets, fonts, licenses, pinned dependencies, and a script to render the document locally.
  39. Keep the ZIP unchanged, then choose **Open saved project** in the playground to continue editing on a later visit.
  40. If the output needs work, [report a rendering problem](https://github.com/fullbleed-engine/fullbleed-official/issues/new?template=bug_report.yml) with a small example using data and assets you can share publicly. For a guided Python walkthrough, use the [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 below.
  41. ### Python
  42. Python 3.10–3.15 on Windows, macOS, or Linux:
  43. ```bash
  44. python -m pip install fullbleed
  45. ```
  46. Save this as `hello.py`, then run `python hello.py`:
  47. ```python
  48. from pathlib import Path
  49. import fullbleed
  50. html = "<h1>Invoice INV-1042</h1><p>Consulting: USD 1,200.00</p>"
  51. css = "@page { size: A4; margin: 20mm; } h1 { color: #175c52; }"
  52. pdf = fullbleed.PdfEngine().render_pdf(html, css)
  53. Path("invoice.pdf").write_bytes(pdf)
  54. ```
  55. 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`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/examples/quickstart/hello.py).
  56. ### Node.js
  57. Use Node.js 22 or newer. Run `npm install fullbleed`, save this as `invoice.mjs`, then run `node invoice.mjs`:
  58. ```javascript
  59. import { writeFile } from 'node:fs/promises';
  60. import { renderPdf } from 'fullbleed';
  61. const result = await renderPdf({
  62. html: '<h1>Invoice INV-1042</h1><p>Consulting: USD 1,200.00</p>',
  63. css: '@page { size: A4; margin: 20mm } h1 { color: #175c52 }',
  64. previewDpi: 96,
  65. });
  66. await writeFile('invoice.pdf', result.pdf);
  67. await writeFile('invoice.png', result.previews[0]);
  68. ```
  69. Open `invoice.pdf` or its PNG preview. The [Node.js quickstart](https://docs.fullbleed.dev/getting-started/node/) includes a downloadable designed invoice project. The separate [Node package](https://github.com/fullbleed-engine/fullbleed-node) supports ESM, CommonJS, and TypeScript. For an application route, use the [Next.js starter](https://docs.fullbleed.dev/guides/nextjs-pdf/).
  70. ### Browser JavaScript
  71. [Try the editable browser app](https://docs.fullbleed.dev/assets/browser-demo/index.html)
  72. to generate an invoice or report, change its HTML/CSS, and download the PDF.
  73. Rendering runs locally in a Web Worker; the starter does not upload document
  74. inputs to a rendering service.
  75. To build on it, [download the complete project](https://docs.fullbleed.dev/assets/browser-starter/project.zip).
  76. Extract the ZIP, open a terminal in `fullbleed-browser-starter`, and use Node.js
  77. 22.12 or newer for the development tools:
  78. ```sh
  79. npm ci
  80. npm run dev
  81. ```
  82. Open the localhost URL printed by Vite. The [browser guide](https://docs.fullbleed.dev/guides/browser-pdf/)
  83. explains adding `fullbleed/browser` to an existing app, serving its runtime
  84. assets over HTTPS or localhost, cancellation, custom fonts, and static deployment.
  85. This renders supplied static HTML/CSS; it does not capture a live browser page.
  86. ### Rust
  87. 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 [latest hosted Rust API reference](https://docs.rs/fullbleed/latest/fullbleed/).
  88. ### C# and .NET
  89. Install [`FullBleed.DotNet`](https://www.nuget.org/packages/FullBleed.DotNet) in a .NET 8, 9, or 10 project and follow the [C# quickstart](https://docs.fullbleed.dev/getting-started/dotnet/). Compose documents with ordinary methods, LINQ children and immutable style objects. The [component guide](https://docs.fullbleed.dev/guides/csharp-components/) explains `WithClass`, attached stylesheets and inline overrides and includes a complete invoice download with explicit fonts. Existing HTML/CSS templates remain supported. Native rendering runs inside the .NET process on Windows x64, Linux x64, Intel macOS, and Apple Silicon macOS, without a Python or browser runtime.
  90. <a id="compose-documents-in-python"></a>
  91. ## Author with reusable components
  92. Components are another way to author the same print documents. Use ordinary
  93. functions, children and reusable styles instead of writing HTML strings:
  94. - [Python components and styling](https://docs.fullbleed.dev/guides/python-components/) — the stable `fullbleed.ui` API includes function components, `class_name` and document stylesheets.
  95. - [JavaScript functions and JSX/TSX](https://docs.fullbleed.dev/guides/javascript-components/) — try the [live invoice](https://docs.fullbleed.dev/assets/react-demo/) or customize the [React starter](https://docs.fullbleed.dev/guides/react-pdf/).
  96. - [C# components and styles](https://docs.fullbleed.dev/guides/csharp-components/) — compose documents with typed methods, LINQ and immutable styles.
  97. <a id="try-the-python-component-alpha"></a>
  98. ### Python release channels
  99. | Channel | Install | Component API |
  100. | --- | --- | --- |
  101. | [Stable release](https://pypi.org/project/fullbleed/) | `python -m pip install fullbleed` | Existing HTML/CSS rendering and `fullbleed.ui` components |
  102. | Opt-in alpha **2.6.0a14** | `python -m pip install --pre "fullbleed==2.6.0a14"` | `fullbleed.components`: owned styles, named parts, data tables, static Bootstrap helpers, page bands and styled/unstyled HTML export |
  103. The component API remains experimental:
  104. independent-kit integration and independent author feedback still need to be
  105. settled. `fullbleed.components` is the intended public namespace for the 2.6 API.
  106. Existing `fullbleed.ui` imports remain supported, and earlier alpha imports from
  107. `fullbleed.ui.experimental` expose the same objects. See the [release-status review and graduation
  108. criteria](https://docs.fullbleed.dev/guides/component-status/) or
  109. [read the current component guide](https://docs.fullbleed.dev/guides/component-preview-12/).
  110. The language packages have their own versions and API coverage.
  111. The alpha also adds [native PDF links](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/pdf-links.md)
  112. for both HTML and component authors, including internal destinations and wrapped
  113. links. This navigation work is separate from the stable 2.5 API and requires
  114. alpha 14 rather than an earlier alpha kit.
  115. The [complete-document migration guide](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/component-namespace.md) maps
  116. styles, page geometry, metadata, fonts and renderer options from the existing
  117. API. Its paired portrait and landscape reports preserve PDF text and rendered
  118. output. Both styled and unstyled HTML exports remain available.
  119. ## Choose your starting point
  120. | You want to build | Start here |
  121. | --- | --- |
  122. | Distinctive invoices, reports, notices, and statements | [Designed showcase with fonts and source](https://docs.fullbleed.dev/examples/) |
  123. | A native Rust application | [Rust quickstart and runnable examples](https://docs.fullbleed.dev/getting-started/rust/) |
  124. | A Node.js or TypeScript application | [Node quickstart and designed invoice project](https://docs.fullbleed.dev/getting-started/node/) |
  125. | PDFs generated in your web application's browser | [Browser worker SDK, editable demo, and complete project](https://docs.fullbleed.dev/guides/browser-pdf/) |
  126. | A C# or .NET application | [NuGet quickstart and designed invoice](https://docs.fullbleed.dev/getting-started/dotnet/) |
  127. | An invoice from JSON | [Complete, checked example](https://github.com/fullbleed-engine/fullbleed-official/tree/v2.6.0a14/examples/agent_workflows) |
  128. | Automatic rebuilds while editing HTML/CSS (2.5.0+) | [Watch-mode invoice example](https://docs.fullbleed.dev/guides/render-watch/) |
  129. | Catch PDF changes in pull requests | [Standalone project with a reviewed baseline and CI workflow](https://docs.fullbleed.dev/guides/pdf-regression-ci/) |
  130. | A PDF download in FastAPI, Flask, or Django | [Runnable web app examples](https://docs.fullbleed.dev/guides/web-frameworks/) |
  131. | Queued PDF invoices in Laravel | [Blade templates, retries, and private downloads (PHP and Python)](https://docs.fullbleed.dev/guides/laravel-pdf/) |
  132. | A PDF response from Rust and Axum | [Invoice endpoint with request limits and editable templates](https://docs.fullbleed.dev/guides/axum-pdf/) |
  133. | PDF generation in AWS Lambda | [Python container starter with local runtime checks](https://docs.fullbleed.dev/guides/aws-lambda-pdf/) |
  134. | PDF attachments in an n8n workflow | [Webhook-to-PDF workflow and local Docker kit](https://docs.fullbleed.dev/guides/n8n-pdf/) |
  135. | A styled PDF report from a pandas DataFrame | [Paginated report with CSV data and verification](https://docs.fullbleed.dev/guides/pandas-to-pdf/) |
  136. | A styled invoice from CSV | [Acme invoice project](https://github.com/fullbleed-engine/fullbleed-official/tree/v2.6.0a14/examples/acme_invoice) |
  137. | Simplified Chinese and English in one PDF | [Bilingual invoice with explicit fonts and glyph checks](https://docs.fullbleed.dev/guides/chinese-pdf/) |
  138. | A report that flows across pages | [Business report example](https://github.com/fullbleed-engine/fullbleed-official/tree/v2.6.0a14/examples/agent_workflows) |
  139. | Tagged output with accessibility checks | [Accessibility workflow](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/ui-accessibility.md) |
  140. | Many documents from one template | [Fixed and reflowing variable-data examples](https://github.com/fullbleed-engine/fullbleed-official/tree/v2.6.0a14/examples/agent_workflows) |
  141. | Print profiles and PDF/VT record hierarchies | [Print output and verification scope](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/pdf-vt.md) |
  142. | A coding-agent or MCP integration | [Agent setup](#agent-discovery-and-integrations) |
  143. [See generated PDFs and their source →](https://docs.fullbleed.dev/examples/)
  144. ## Why use Fullbleed?
  145. - **Simple deployment:** prebuilt wheels for 15 platform targets, with no browser or system-font installation needed for the bundled workflow.
  146. - **Repeatable documents:** explicit assets and metadata, deterministic rendering, and SHA-256 reproducibility checks.
  147. - **Document-focused layout:** pagination, headers and footers, tables, template overlays, and per-page data.
  148. - **Volume workflows:** compile a template once, then bind fixed or reflowing records. [Measured workloads and limits](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/performance-pass-2026-08-04.md).
  149. - **Inspectable output:** PDF inspection, PNG previews, structured diagnostics, and profile verification tooling.
  150. Native previews of unembedded Standard 14 fonts use compact bundled outline
  151. substitutes, so basic Helvetica, Times, Courier, Symbol, and Dingbats text renders
  152. without system fonts. Registered and embedded font programs take precedence.
  153. The font-resolution trace identifies the `bundled_substitute` outcome; runtime
  154. discovery reports `bundled_standard_font_previews`. See the
  155. [font sources, licenses, and coverage limits](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/src/preview_fonts/README.md).
  156. Fullbleed uses static HTML/CSS as a document layout language. Check the [CSS coverage and remaining gaps](https://github.com/fullbleed-engine/fullbleed-official/blob/master/docs/css-coverage.md) for your templates. Use a browser when JavaScript or live website behavior is part of the required result.
  157. Profile selection alone does not establish standards conformance. The [release evidence](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/release/2.4.0-validation-report.md) records the checks performed and their limits.
  158. ## Get help and contribute
  159. 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](https://github.com/fullbleed-engine/fullbleed-official/blob/master/CONTRIBUTING.md) covers local setup, tests, and where to make changes.
  160. If Fullbleed is useful to you, [support its maintenance](https://docs.fullbleed.dev/support/) through sponsorship, documentation, or a useful example. Sponsorship is optional; Fullbleed remains MIT licensed and free to use.
  161. ## Agent discovery and integrations
  162. 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:
  163. ```bash
  164. fullbleed agent-manifest --json
  165. # Equivalent canonical form:
  166. fullbleed agent-contract --format json
  167. ```
  168. The committed [`fullbleed-agent-contract.json`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/fullbleed-agent-contract.json), [`cli_schema.md`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/cli_schema.md), and [`llms.txt`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/llms.txt) are generated from the built wheel. CI rejects version, command, schema, profile, or capability drift. Runtime introspection remains authoritative.
  169. The first-party, versionless [`skills/fullbleed/SKILL.md`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/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:
  170. ```bash
  171. fullbleed agent skill-path --json
  172. fullbleed agent export-skill .agents/skills/fullbleed --json
  173. ```
  174. 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.
  175. For tool-calling agents, install the separately versioned adapter so the core package remains dependency-free:
  176. ```bash
  177. python -m pip install fullbleed-mcp
  178. fullbleed-mcp --root .
  179. ```
  180. 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 .`.
  181. 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.
  182. Cold-agent testing is available through `fullbleed agent-acceptance`; compact copyable workflows live in [`examples/agent_workflows`](https://github.com/fullbleed-engine/fullbleed-official/tree/v2.6.0a14/examples/agent_workflows), and the approach-neutral benchmark scaffold lives in [`agentdocbench`](https://github.com/fullbleed-engine/fullbleed-official/tree/v2.6.0a14/agentdocbench).
  183. This README is the canonical usage guide for:
  184. - `fullbleed` CLI (human workflows + machine/agent automation)
  185. - `fullbleed` Python bindings (`PdfEngine`, `AssetBundle`, batch APIs)
  186. Additional focused references are in `docs/`:
  187. - `docs/install-non-technical.md` (step-by-step setup for non-technical users)
  188. - `docs/css-coverage.md` (validated CSS coverage, parity status, and active gaps)
  189. - `docs/README.md`
  190. - `docs/engine.md`
  191. - `docs/performance-architecture.md`
  192. - `docs/performance-pass-2026-08-04.md`
  193. - `docs/python-api.md`
  194. - `docs/ui-accessibility.md`
  195. - `docs/cli.md`
  196. - `docs/pdf-templates.md`
  197. ## What You Get
  198. - No headless browser requirement for PDF generation.
  199. - Deterministic render pipeline with optional SHA256 output hashing.
  200. - Reproducibility workflow via `--repro-record` and `--repro-check`.
  201. - PDF `1.7` as the production-stable default target.
  202. - Rust-native PDF template composition for VDP/transactional overlays.
  203. - Native Rust image emission for overlay and finalized compose outputs (`--emit-image`) without external PDF raster runtime dependencies.
  204. - Feature-driven page-to-template binding with per-page deterministic compose plans.
  205. - Structured JSON result schemas for CI and AI agents.
  206. - Offline-first asset model with explicit remote opt-in.
  207. - Remote project template registry workflows (`new list`, `new search`, `new remote`).
  208. - Python-first extension surface for hackability and custom workflows.
  209. - Python render calls release the GIL while Rust rendering executes.
  210. - Ordered standard-library worker pools for batch rendering and selected internal workloads.
  211. - A deliberately small, license-audited Rust dependency graph and no required third-party Python
  212. runtime or build packages.
  213. ## Concurrency Model
  214. - Python binding render methods release the GIL during Rust execution through the Stable ABI bridge.
  215. - Parallel batch APIs use Fullbleed's ordered standard-library worker pool (`render_pdf_batch_parallel(...)` and parallel-to-file variants).
  216. - The same bounded worker implementation serves selected internal hotspots such as table layout and JIT paint paths.
  217. - Do not assume every single-document render path will fully saturate all cores end-to-end.
  218. ## Performance in 2.2
  219. Fullbleed 2.2 retains exact TrueType glyph subsetting and adds compiled fixed-geometry variable-data
  220. binding. Across the five independent benchmark fixtures, PDFs are 95.5-97.3% smaller and ordinary
  221. warm rendering is 2.90x faster by geometric mean than released 2.0.0.
  222. The new compile-once API freezes an immutable Q32.32 display document and can link it repeatedly
  223. without rerunning HTML parsing, selector matching, layout, pagination, or command planning. For
  224. identical untagged copies in one ordered PDF, `CompiledDocument.render_pdf_batch(...)` shares each
  225. source page's content stream across the copied page dictionaries. The measured 20-copy lane is
  226. 200.7x faster per page by geometric mean than the released 2.0.0 warm renderer; a 1,000-page stress
  227. run sustained 304,479-666,622 pages/s.
  228. The 2.2 compiler includes a genuine fixed-geometry variable-data lane. A compiled invoice
  229. with six bound fields rendered 100,000 distinct records in a five-run median of 283.807 ms to
  230. memory (**352,352 pages/s**) and 295.999 ms directly to a flushed 88.1 MB PDF
  231. (**337,839 pages/s**). Including the one-time 4.168 ms compile gives 333,147 direct-file pages/s.
  232. The harness verified all 100,000 unique invoice IDs in page order, exact page count, resolved
  233. markers, deterministic bytes, and equal buffer/file SHA-256. Reproduce it with:
  234. ```bash
  235. python tools/benchmark_fullbleed_vdp.py --records 100000 --repeats 5
  236. ```
  237. Fixed-geometry slots may remain inside immutable page-space transforms and clips. The compiler
  238. captures that active coordinate-state program once and replays it in each compact record overlay;
  239. it does not rerun layout or clone the complete page display list.
  240. Base-14/WinAnsi slot paint keeps the measured byte-patch linker. Registered embedded fonts use a
  241. command-level overlay program so each bound value is shaped and included in the font subset while
  242. the compiled layout, pagination, and static page stream remain shared. The throughput figures above
  243. describe the Base-14 fast lane; they are not claims for registered-font shaping.
  244. The fixed-copy result remains scoped to identical content; the variable-data result is scoped to
  245. paint-only text whose geometry does not reflow. Neither is a claim that arbitrary new HTML or
  246. size-changing records render 200x faster. See
  247. [`docs/performance-pass-2026-08-04.md`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/performance-pass-2026-08-04.md) for measurements and
  248. [`docs/performance-architecture.md`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/performance-architecture.md) for the packed vector IR,
  249. typed-binding, virtual-linker, and shader roadmap.
  250. Fullbleed 2.2.5 hardens the third compiler lane introduced in 2.2.4 for
  251. size-changing records: `CompiledDocument.render_pdf_reflow_bindings(...)`. It parses and recovers
  252. the template DOM once and compiles encountered structural flow variants into guarded fixed-point
  253. display programs. Matching records bind directly into those programs; workers execute pre-shaped
  254. text/TJ paint slots, cached static PDF page segments, page-local Deflate, and one ordered linker.
  255. Explicit trusted structural slots use `data-fb-bind-html="slot"`. A value that no compiled variant
  256. can safely place runs ordinary fixed-point layout once to add another variant.
  257. On the independent 1,000-distinct-record case study, the 29-sample hot direct-file median was
  258. 216.160 ms: **4,626 records/s and 8,096 pages/s**. The 168.995 ms best sample reached **5,917
  259. records/s and 10,355 pages/s**. It produced
  260. the exact 1,750-page 500/300/150/50 reflow distribution and verified all 24,900 markers. The
  261. throughput-tuned 6,870,320-byte PDF was deterministic across all samples. With the compact
  262. compression setting, compiled output was also byte-for-byte identical to ordinary rendering:
  263. 5,298,961 bytes and SHA-256 `bb3c441313a08fb00d3bd15f23a567981f3bbbd550908e3a9fe7a07ca5d7f138`.
  264. This is a hot compiled-variant result, not a claim for previously unseen structure. The first
  265. variant-discovery render measured 0.509 s (3,437 pages/s), and the fully cold job including setup,
  266. bindings, compilation, discovery, and write measured 0.588 s (2,975 pages/s). The independently
  267. observed hot-median speedup over the ordinary path was 43.8x.
  268. ## Install
  269. New to Python or setting up on a fresh machine? Start with `docs/install-non-technical.md`.
  270. ```bash
  271. python -m pip install fullbleed
  272. ```
  273. From a local wheel:
  274. ```bash
  275. python -m pip install C:\path\to\fullbleed-2.6.0a14-cp310-abi3-win_amd64.whl
  276. ```
  277. From a source checkout with Rust installed, no Python build package is needed:
  278. ```bash
  279. python -m pip install --no-build-isolation --no-deps --editable .
  280. ```
  281. To create deterministic release artifacts directly:
  282. ```bash
  283. python build_backend/fullbleed_build_backend.py wheel --out dist
  284. python build_backend/fullbleed_build_backend.py sdist --out dist
  285. ```
  286. Platform artifact policy:
  287. - Linux wheels cover `manylinux2014` on x86-64, x86, ARM64, ARMv7, s390x,
  288. and ppc64le, plus `musllinux_1_2` on x86-64, x86, ARM64, and ARMv7.
  289. - Windows wheels cover x86-64, x86, and ARM64; macOS wheels cover Intel and
  290. Apple silicon.
  291. - The CPython stable ABI allows each platform wheel to support Python 3.10
  292. through 3.15 on standard-GIL CPython.
  293. - CI installs and exercises every built wheel on its target architecture,
  294. using native runners or QEMU as appropriate. The x86-64 manylinux wheel is
  295. additionally tested on every supported Python version before publication.
  296. Python 3.15 final checks exercise both the development wheel and public stable
  297. release. They run the matching Python suite and compare PDFs and previews byte
  298. for byte against Python 3.10. Published-wheel checks cover Windows and Linux
  299. x64 plus Intel and Apple-silicon Macs. See the
  300. [compatibility evidence and its scope](https://github.com/fullbleed-engine/fullbleed-official/blob/master/docs/python-compatibility.md).
  301. Verify command surface:
  302. ```bash
  303. fullbleed --help
  304. fullbleed capabilities --json
  305. fullbleed doctor --json
  306. ```
  307. ## 60-Second Quick Start (Project Happy Path)
  308. Initialize project scaffold:
  309. ```bash
  310. fullbleed init .
  311. ```
  312. `fullbleed init` now vendors Bootstrap (`5.0.0`) into `vendor/css/bootstrap.min.css`,
  313. vendors Bootstrap Icons (`1.11.3`) into `vendor/icons/bootstrap-icons.svg`,
  314. vendors `inter` into `vendor/fonts/Inter-Variable.ttf`, writes license notices
  315. (`vendor/css/LICENSE.bootstrap.txt`, `vendor/icons/LICENSE.bootstrap-icons.txt`, `vendor/fonts/LICENSE.inter.txt`),
  316. and seeds `assets.lock.json` with pinned hashes.
  317. The scaffolded `report.py` also runs a component mount smoke validation before
  318. main render and writes `output/component_mount_validation.json` (fails fast on
  319. missing glyphs, actual pagination overflow, or CSS miss signals). On current engines,
  320. render-time pagination is authoritative for overflow; conservative JIT placement bounds
  321. remain the compatibility fallback for older engines.
  322. Scaffolded components now include `components/primitives.py` with reusable
  323. layout/content helpers (`Stack`, `Row`, `Text`, table/list helpers, key/value rows, etc.).
  324. Each scaffolded project also includes `SCAFFOLDING.md`, which should be your
  325. first read before restructuring components.
  326. It also includes `AGENTS.md`, which preserves the installed-runtime-first
  327. document workflow across future coding-agent sessions without making other
  328. document tools categorically forbidden.
  329. Install additional project assets (defaults to `./vendor/...` in project context):
  330. ```bash
  331. fullbleed assets install inter --json
  332. ```
  333. Bootstrap baseline note:
  334. - We target Bootstrap (`5.0.0`) as the default styling baseline for project workflows.
  335. - Re-run `fullbleed assets install bootstrap --json` only if you want to explicitly refresh/bootstrap-manage outside `init`.
  336. Render using the scaffolded component pipeline:
  337. ```bash
  338. python report.py
  339. ```
  340. Expected artifacts from scaffolded `report.py`:
  341. - `output/report.pdf`
  342. - `output/report_page1.png` (or equivalent page preview from engine image APIs)
  343. - `output/component_mount_validation.json`
  344. - `output/css_layers.json`
  345. Canonical static PDF reference:
  346. ```bash
  347. python examples/canonical_reference/report.py
  348. ```
  349. `examples/canonical_reference/` is the exhaustive scaffold-shaped reference for
  350. component composition, layered CSS, bundled fonts/SVG, inline SVG, raster data
  351. URIs, linked and standalone HTML artifacts, PDF output, PNG previews, and
  352. validation reports.
  353. ## Project Bootstrap Templates (`fullbleed new`)
  354. Use local starters:
  355. ```bash
  356. fullbleed new local invoice ./my-invoice
  357. fullbleed new local statement ./my-statement
  358. fullbleed new local accessible ./my-accessible-doc
  359. fullbleed new local reference ./my-reference-doc
  360. ```
  361. Discover remote starters from the registry:
  362. ```bash
  363. fullbleed new list --json
  364. fullbleed new search components --json
  365. fullbleed new remote component-showcase ./my-documents --version 0.1.3 --json
  366. ```
  367. The showcase contains the Northstar invoice and Common Ground report in both
  368. HTML/CSS and Python components, plus the authored accessible community guide.
  369. The paired designs share data, fonts, CSS and artwork. The
  370. installer copies source files; it does not install dependencies or execute the
  371. project. Each kit pins its tested component prerelease in `requirements.txt`.
  372. Follow the [kit guide pinned to alpha 8](https://docs.fullbleed.dev/guides/component-preview-8/)
  373. to install it in a separate environment, compare the four pages, and edit with
  374. a live PDF preview. For a smaller starting point, choose the
  375. [`python-components` starter](https://docs.fullbleed.dev/guides/bootstrap-components-preview/)
  376. at template version `0.1.2`; that smaller kit retains its tested a6 runtime pin.
  377. `fullbleed new local accessible` is the verbose accessibility-first starter and
  378. demonstrates the `fullbleed.accessibility` runtime surface (engine verifier,
  379. PMR, PDF/UA-targeted seed checks, and non-visual trace artifacts).
  380. `fullbleed new local reference` vendors the canonical static PDF reference shape
  381. as a scaffolded project with component layers, assets, PDF/PNG outputs, page data,
  382. and validation reports.
  383. Optional registry override (for private/canary registries):
  384. ```bash
  385. fullbleed new list --registry https://example.com/manifest.json --json
  386. ```
  387. or:
  388. ```bash
  389. set FULLBLEED_TEMPLATE_REGISTRY=https://example.com/manifest.json
  390. fullbleed new search statement --json
  391. ```
  392. ## Scaffold-First Workflow (Recommended)
  393. `fullbleed init` is designed for component-first authoring rather than a single large HTML template.
  394. Typical scaffold layout:
  395. ```text
  396. .
  397. |-- SCAFFOLDING.md
  398. |-- COMPLIANCE.md
  399. |-- report.py
  400. |-- components/
  401. | |-- fb_ui.py
  402. | |-- primitives.py
  403. | |-- header.py
  404. | |-- body.py
  405. | |-- footer.py
  406. | `-- styles/
  407. | |-- primitives.css
  408. | |-- header.css
  409. | |-- body.css
  410. | `-- footer.css
  411. |-- styles/
  412. | |-- tokens.css
  413. | `-- report.css
  414. |-- vendor/
  415. | |-- css/
  416. | |-- fonts/
  417. | `-- icons/
  418. `-- output/
  419. ```
  420. Best-practice authoring model:
  421. 1. Read `SCAFFOLDING.md` first for project conventions.
  422. 2. Keep composition and data loading in `report.py`.
  423. 3. Keep reusable component building blocks in `components/primitives.py`.
  424. 4. Keep section markup in `components/header.py`, `components/body.py`, `components/footer.py`.
  425. 5. Keep component-local styles in `components/styles/*.css`.
  426. 6. Keep page tokens/composition styles in `styles/tokens.css` and `styles/report.css`.
  427. Recommended CSS layer order:
  428. 1. `styles/tokens.css`
  429. 2. `components/styles/primitives.css`
  430. 3. `components/styles/header.css`
  431. 4. `components/styles/body.css`
  432. 5. `components/styles/footer.css`
  433. 6. `styles/report.css`
  434. Recommended iteration loop:
  435. 1. Edit data loading + component props in `report.py`.
  436. 2. Edit component markup in `components/*.py`.
  437. 3. Edit styles in `components/styles/*.css` and `styles/*.css`.
  438. 4. Run `python report.py`.
  439. 5. Review `output/report_page1.png`, `output/component_mount_validation.json`, and `output/css_layers.json`.
  440. Optional scaffold diagnostics:
  441. - `FULLBLEED_DEBUG=1` to emit JIT traces.
  442. - `FULLBLEED_PERF=1` to emit perf traces.
  443. - `FULLBLEED_EMIT_PAGE_DATA=1` to persist page data JSON.
  444. - `FULLBLEED_IMAGE_DPI=144` (or higher) for preview resolution.
  445. - `FULLBLEED_VALIDATE_STRICT=1` for stricter validation gates in CI.
  446. ## One-off Quick Render (No Project Scaffold)
  447. Render inline HTML/CSS with reproducibility artifacts:
  448. ```bash
  449. fullbleed --json render \
  450. --html-str "<html><body><h1>Hello</h1></body></html>" \
  451. --css-str "body{font-family:sans-serif}" \
  452. --emit-manifest build/render.manifest.json \
  453. --emit-jit build/render.jit.jsonl \
  454. --emit-perf build/render.perf.jsonl \
  455. --deterministic-hash build/render.sha256 \
  456. --repro-record build/render.repro.json \
  457. --out output/hello.pdf
  458. ```
  459. `--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.
  460. Re-run and enforce reproducibility against a stored record:
  461. ```bash
  462. fullbleed --json render \
  463. --html templates/report.html \
  464. --css templates/report.css \
  465. --repro-check build/render.repro.json \
  466. --out output/report.rerun.pdf
  467. ```
  468. Generate PNG page artifacts from an existing validation render:
  469. ```bash
  470. fullbleed --json verify \
  471. --html templates/report.html \
  472. --css templates/report.css \
  473. --emit-pdf output/report.verify.pdf \
  474. --emit-image output/report_verify_pages \
  475. --image-dpi 200
  476. ```
  477. Compile-only plan (no render):
  478. ```bash
  479. fullbleed --json plan \
  480. --html templates/report.html \
  481. --css templates/report.css
  482. ```
  483. Template compose planning (no finalize write):
  484. ```bash
  485. fullbleed --json plan \
  486. --html templates/overlay.html \
  487. --css templates/overlay.css \
  488. --template-binding config/template_binding.json \
  489. --templates config/template_catalog.json \
  490. --emit-compose-plan output/compose_plan.json
  491. ```
  492. ## PDF Template Composition (VDP / Transactional)
  493. When overlaying variable data onto a source PDF, use the built-in Rust template compose path.
  494. Minimal CLI auto-compose flow:
  495. ```bash
  496. fullbleed --json render \
  497. --html templates/overlay.html \
  498. --css templates/overlay.css \
  499. --asset templates/source.pdf --asset-kind pdf --asset-name source-template \
  500. --template-binding config/template_binding.json \
  501. --templates config/template_catalog.json \
  502. --out output/composed.pdf
  503. ```
  504. Compose image semantics:
  505. - In template auto-compose mode, `--emit-image` PNGs are rasterized from finalized composed pages and report `outputs.image_mode=composed_pdf`.
  506. - In non-compose `render`/`verify` runs, `--emit-image` reports `outputs.image_mode=overlay_document`.
  507. Minimal `template_binding` example:
  508. ```json
  509. {
  510. "default_template_id": "source-template",
  511. "feature_prefix": "fb.feature.",
  512. "by_feature": {
  513. "front": "source-template",
  514. "back_blank": "source-template"
  515. }
  516. }
  517. ```
  518. Python API compose flow:
  519. ```python
  520. import fullbleed
  521. engine = fullbleed.PdfEngine(template_binding=binding_spec)
  522. overlay_bytes, _page_data, _bindings = engine.render_pdf_with_page_data_and_template_bindings(html, css)
  523. open("output/overlay.pdf", "wb").write(overlay_bytes)
  524. plan_result = engine.plan_template_compose(
  525. html,
  526. css,
  527. [("source-template", "templates/source.pdf")],
  528. 0.0,
  529. 0.0,
  530. )
  531. plan = [
  532. (
  533. row["template_id"],
  534. row["template_page"],
  535. row["overlay_page"],
  536. row["dx"],
  537. row["dy"],
  538. )
  539. for row in plan_result["plan"]
  540. ]
  541. fullbleed.finalize_compose_pdf(
  542. [("source-template", "templates/source.pdf")],
  543. plan,
  544. "output/overlay.pdf",
  545. "output/composed.pdf",
  546. annotation_mode="link_only", # optional: link_only | none | carry_widgets
  547. )
  548. ```
  549. See `docs/pdf-templates.md` and `examples/template-flagging-smoke/` for full production examples.
  550. ## CLI Command Map
  551. | Command | Purpose | JSON Schema |
  552. | --- | --- | --- |
  553. | `render` | Render HTML/CSS to PDF with optional PNG page artifacts | `fullbleed.render_result.v1` |
  554. | `verify` | Validation render path with optional PDF and PNG emits | `fullbleed.verify_result.v1` |
  555. | `plan` | Compile/normalize inputs into manifest + warnings | `fullbleed.plan_result.v1` |
  556. | `run` | Render using Python module/file engine factory | `fullbleed.run_result.v1` |
  557. | `inspect pdf` | Inspect PDF metadata and composition compatibility | `fullbleed.inspect_pdf.v1` |
  558. | `inspect pdf-batch` | Inspect multiple PDFs with per-file status | `fullbleed.inspect_pdf_batch.v1` |
  559. | `inspect templates` | Inspect template catalog metadata/compatibility | `fullbleed.inspect_templates.v1` |
  560. | `compliance` | License/compliance report for legal/procurement | `fullbleed.compliance.v1` |
  561. | `debug-perf` | Summarize perf JSONL logs | `fullbleed.debug_perf.v1` |
  562. | `debug-jit` | Filter/inspect JIT JSONL logs | `fullbleed.debug_jit.v1` |
  563. | `doctor` | Runtime capability and health checks | `fullbleed.doctor.v1` |
  564. | `capabilities` | Machine-readable command/engine capabilities | `fullbleed.capabilities.v1` |
  565. | `assets list` | Installed and optional remote packages | `fullbleed.assets_list.v1` |
  566. | `assets info` | Package details + hashes/sizes | `fullbleed.assets_info.v1` |
  567. | `assets install` | Install builtin/remote package | `fullbleed.assets_install.v1` |
  568. | `assets verify` | Validate package and optional lock constraints | `fullbleed.assets_verify.v1` |
  569. | `assets lock` | Write/update `assets.lock.json` | `fullbleed.assets_lock.v1` |
  570. | `cache dir` | Cache location | `fullbleed.cache_dir.v1` |
  571. | `cache prune` | Remove old cached packages | `fullbleed.cache_prune.v1` |
  572. | `init` | Initialize project scaffold | `fullbleed.init.v1` |
  573. | `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` |
  574. Schema discovery for any command/subcommand:
  575. ```bash
  576. fullbleed --schema render
  577. fullbleed --schema assets verify
  578. fullbleed --schema inspect pdf
  579. fullbleed --schema inspect templates
  580. ```
  581. ## CLI Flags That Matter Most
  582. Global machine flags:
  583. - `--json`: structured result payload to stdout
  584. - `--json-only`: implies `--json` and `--no-prompts`
  585. - `--schema`: emit schema definition and exit
  586. - `--no-prompts`: disable interactive prompts
  587. - `--config`: load defaults from a config file
  588. - `--log-level error|warn|info|debug`: control CLI log verbosity
  589. - `--no-color`: disable ANSI color output
  590. - `--version`: print CLI version and exit
  591. Render/verify/plan key flags:
  592. - Inputs: `--html`, `--html-str`, `--css`, `--css-str`
  593. `--html` accepts `.svg` files for direct SVG-document rendering; `--html-str` accepts inline SVG markup.
  594. - Page setup: `--page-size`, `--page-width`, `--page-height`, `--margin`, `--page-margins`
  595. - Engine toggles: `--reuse-xobjects`, `--svg-form-xobjects`, `--svg-raster-fallback`, `--shape-text`, `--unicode-support`, `--unicode-metrics`
  596. - PDF/compliance: `--pdf-version`, `--pdf-profile`, `--color-space`, `--document-lang`, `--document-title`
  597. Stable default is `--pdf-version 1.7` for shipping workflows.
  598. Profile targets: `none`, `pdfa1a`, `pdfa1b`, `pdfa2a`, `pdfa2b`, `pdfa2u`, `pdfa3a`, `pdfa3b`, `pdfa3u`, `pdfa4`, `pdfa4e`, `pdfa4f`, `pdfx4`, `pdfua1`, `pdfua2`, `pdfvt1`, `wtpdf1r`, `wtpdf1a`, `tagged`.
  599. Aliases: `a`, `ua`, `vt`, `wt1r`, `wt1a`, `pdf/a`, `pdf/ua`, `pdf/vt`.
  600. Output intent metadata (`--output-intent-identifier|--output-intent-info|--output-intent-components`) requires `--output-intent-icc`.
  601. `pdfx4` and `pdfvt1` force PDF 1.6 and require a title and explicit write date
  602. (`--timestamp current`, a fixed UTC date, or `--timestamp-source SOURCE_DATE_EPOCH`).
  603. [PDF/VT composition](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/pdf-vt.md) documents record hierarchies, `--pdf-vt-job`,
  604. private DPM, conservative reuse hints, and the independent release-validation boundary.
  605. Run `python tools/validate_pdf_profiles.py --download-verapdf --install-pdf-oxide --strict-external`
  606. to regenerate profile specimens, capture inspect/JIT evidence, replay
  607. deterministic hashes, validate PDF/A and PDF/UA with veraPDF, and validate
  608. PDF/X-4 with `pdf_oxide`. WTPDF profiles are validated with veraPDF
  609. `wt1r`/`wt1a` and include PDF Declaration evidence. `pdfa4f` emits and
  610. checks an associated `EmbeddedFiles` name tree. `pdfvt1` also emits and checks a parsed
  611. DPart graph (`DPartRoot`, `DPartRootNode`, `NodeNameList [/Job /Record /Document]`, leaf page range,
  612. and page `/DPart` references), including a supplemental multipage specimen
  613. for `/Start` and `/End`, reported as granular booleans plus
  614. `pdfvt_dpart_graph_valid`; use a dedicated PDF/VT preflight tool
  615. for third-party PDF/VT certification, or wire one into the same harness with
  616. `--pdfvt-cmd "tool --input {pdf}" --pdfvt-version-cmd "tool --version" --require-dedicated-pdfvt`.
  617. - Watermarking: `--watermark-text`, `--watermark-html`, `--watermark-image`, `--watermark-layer`, `--watermark-semantics`, `--watermark-opacity`, `--watermark-rotation`
  618. - Artifacts: `--emit-jit`, `--emit-perf`, `--emit-glyph-report`, `--emit-page-data`, `--emit-compose-plan`, `--emit-image`, `--image-dpi`, `--deterministic-hash`
  619. - Assets: `--asset`, `--asset-kind`, `--asset-name`, `--asset-trusted`, `--allow-remote-assets`
  620. - Profiles: `--profile dev|preflight|prod`
  621. - Fail policy: `--fail-on overflow|missing-glyphs|font-subst|budget`
  622. - Fallback policy: `--allow-fallbacks` (keeps fallback diagnostics, but does not fail `missing-glyphs` / `font-subst` gates)
  623. - Reproducibility: `--repro-record <path>`, `--repro-check <path>`
  624. - Budget thresholds: `--budget-max-pages`, `--budget-max-bytes`, `--budget-max-ms`
  625. - Release gates: `doctor --strict`, `compliance --strict --max-audit-age-days <n>`
  626. ## SVG Workflows
  627. Fullbleed supports SVG in three practical CLI paths:
  628. - Direct SVG document render via `--html <file.svg>`
  629. - Inline SVG markup via `--html-str "<svg ...>...</svg>"`
  630. - Referenced SVG assets via `--asset <file.svg>` (kind auto-infers to `svg`)
  631. Standalone SVG file to PDF:
  632. ```bash
  633. fullbleed --json render \
  634. --html artwork/badge.svg \
  635. --out output/badge.pdf
  636. ```
  637. Inline SVG markup to PDF:
  638. ```bash
  639. fullbleed --json render \
  640. --html-str "<svg xmlns='http://www.w3.org/2000/svg' width='200' height='80'><rect width='200' height='80' fill='#0d6efd'/><text x='16' y='48' fill='white'>Hello SVG</text></svg>" \
  641. --out output/inline-svg.pdf
  642. ```
  643. HTML template with explicit SVG asset registration:
  644. ```bash
  645. fullbleed --json render \
  646. --html templates/report.html \
  647. --css templates/report.css \
  648. --asset assets/logo.svg \
  649. --asset-kind svg \
  650. --out output/report.pdf
  651. ```
  652. SVG render behavior flags:
  653. - `--svg-form-xobjects` / `--no-svg-form-xobjects`
  654. - `--svg-raster-fallback` / `--no-svg-raster-fallback`
  655. Distributed Python wheels enable the `svg_raster` engine feature, so
  656. `--svg-raster-fallback` can rasterize unsupported SVG constructs such as SVG
  657. text, filters, masks, and `foreignObject` into deterministic image content.
  658. Custom source builds must include `--features python,svg_raster` to advertise
  659. and use that fallback path.
  660. Machine discovery:
  661. ```bash
  662. fullbleed capabilities --json
  663. ```
  664. Inspect the `svg` object in `fullbleed.capabilities.v1` for SVG support metadata. The `engine`
  665. object also reports compiled-document/reflow availability and supported per-call compression modes.
  666. It reports the compiled `svg_raster` build feature plus a feature matrix for
  667. native-vector SVG, raster-fallback-required SVG, and unsupported/known-loss SVG
  668. features.
  669. ## Image Support Matrix
  670. Launch-safe image claims:
  671. - Supported direct raster inputs: PNG and JPEG.
  672. - SVG is handled by the SVG pipeline described above, with native-vector output
  673. where supported and raster fallback for fallback-only features when
  674. `svg_raster` is enabled.
  675. - Supported references include filesystem paths, registered bundle assets,
  676. file/data URIs, `<img>`, CSS `background-image: url(...)`, list-style images,
  677. and watermark images.
  678. - Unsupported or not launch-claimed as direct inputs: WebP, GIF, TIFF, AVIF,
  679. BMP, animated images, `<picture>`, `srcset`, `sizes`, density descriptors,
  680. and browser-style responsive image selection.
  681. - For deterministic builds, prefer vendored local assets or registered
  682. `AssetBundle` inputs; remote assets must be explicitly allowed.
  683. ## Per-Page Templates (`page_1`, `page_2`, `page_n`)
  684. Fullbleed uses ordered page templates internally. In docs, this is easiest to think of as:
  685. - `page_1`: first page template
  686. - `page_2`: second page template
  687. - `page_n`: repeating template for later pages
  688. Configuration mapping:
  689. - CLI `--page-margins` keys: `1`, `2`, ... and optional `"n"` (or `"each"` alias).
  690. - Python `PdfEngine(page_margins=...)`: same key model.
  691. - Missing numeric pages fall back to the base `margin`.
  692. - The last configured template repeats for remaining pages.
  693. Minimal CLI example:
  694. ```json
  695. {
  696. "1": {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  697. "2": {"top": "24mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  698. "n": {"top": "30mm", "right": "12mm", "bottom": "12mm", "left": "12mm"}
  699. }
  700. ```
  701. ```bash
  702. fullbleed --json render \
  703. --html templates/report.html \
  704. --css templates/report.css \
  705. --page-margins page_margins.json \
  706. --header-each "Statement continued - Page {page} of {pages}" \
  707. --out output/report.pdf
  708. ```
  709. Minimal Python example:
  710. ```python
  711. import fullbleed
  712. engine = fullbleed.PdfEngine(
  713. page_width="8.5in",
  714. page_height="11in",
  715. margin="12mm",
  716. page_margins={
  717. 1: {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"}, # page_1
  718. 2: {"top": "24mm", "right": "12mm", "bottom": "12mm", "left": "12mm"}, # page_2
  719. "n": {"top": "30mm", "right": "12mm", "bottom": "12mm", "left": "12mm"} # page_n
  720. },
  721. header_first="Account Statement",
  722. header_each="Statement continued - Page {page} of {pages}",
  723. footer_last="Final page",
  724. )
  725. ```
  726. Note:
  727. - CLI currently exposes `--header-each` / `--footer-each` (and `--header-html-each` / `--footer-html-each`).
  728. - For `first/last` header/footer variants (`header_first`, `header_last`, `footer_first`, `footer_last`), use the Python API.
  729. ## Asset Workflow (CLI)
  730. List installed + available packages:
  731. ```bash
  732. fullbleed assets list --available --json
  733. ```
  734. Install builtin assets:
  735. ```bash
  736. fullbleed assets install bootstrap
  737. fullbleed assets install bootstrap-icons
  738. fullbleed assets install inter
  739. # Plain names and quoted @ references are supported.
  740. ```
  741. PowerShell note:
  742. - Quote `@` aliases (for example `"@bootstrap"`) to avoid shell parsing surprises.
  743. Render with bundled Inter directly; no separate asset installation is needed:
  744. ```bash
  745. python -m fullbleed render --html invoice.html --css invoice.css --asset "@inter" --out invoice.pdf
  746. ```
  747. Set `font-family: Inter` in `invoice.css`. The command uses the font bytes in
  748. the installed package, without a network request or a system-font lookup.
  749. `assets install inter` copies that same font and its full OFL license into the
  750. chosen vendor directory or cache. Discover the supported `render_refs` and
  751. `install_refs` through `assets list --json`.
  752. Install broad Unicode fallback package (larger font payload):
  753. ```bash
  754. fullbleed assets install noto-sans
  755. ```
  756. Install to a custom vendor directory:
  757. ```bash
  758. fullbleed assets install bootstrap --vendor ./vendor
  759. ```
  760. Install to global cache:
  761. ```bash
  762. fullbleed assets install inter --global
  763. ```
  764. Install common barcode fonts (license-safe defaults):
  765. ```bash
  766. fullbleed assets install libre-barcode-128
  767. fullbleed assets install libre-barcode-39
  768. fullbleed assets install libre-barcode-ean13-text
  769. ```
  770. Verify against lock file with strict failure:
  771. ```bash
  772. fullbleed assets verify inter --lock --strict --json
  773. ```
  774. Preview cache cleanup without deleting files:
  775. ```bash
  776. fullbleed cache prune --max-age-days 30 --dry-run --json
  777. ```
  778. Notes:
  779. - Builtin packages accept both plain and `@` references (`bootstrap` == `@bootstrap`, `bootstrap-icons` == `@bootstrap-icons`, `noto-sans` == `@noto-sans`, `inter` == `@inter`). Explicit versions must match an included version; unavailable versions are rejected.
  780. - `noto-sans` is available as a builtin fallback package, but it is intentionally larger than `inter`; use it when your document requires broader glyph coverage.
  781. - Project installs default to `./vendor/` when project markers are present (`assets.lock.json`, `report.py`, or `fullbleed.toml` in CWD).
  782. - If no project markers are found, `assets install` defaults to global cache unless `--vendor` is explicitly set.
  783. - Do not hardcode cache paths like `%LOCALAPPDATA%/fullbleed/cache/...`; use `assets install --json` and consume `installed_to`.
  784. - Installed assets include license files in typed vendor directories (for example `vendor/fonts/`, `vendor/css/`).
  785. - `assets lock --add` is currently aimed at builtin package additions.
  786. - Barcode packages in the remote registry are currently OFL-1.1 families from Google Fonts (`Libre Barcode`).
  787. - USPS IMB fonts are not currently auto-installable via `assets install`; use local vetted font files and track licensing separately.
  788. ## Bootstrap Vendoring
  789. Bootstrap builtin package details:
  790. - Package: `bootstrap` (alias: `@bootstrap`)
  791. - Bundled version: `5.0.0`
  792. - Asset kind: CSS (`bootstrap.min.css`)
  793. - Default install location: `vendor/css/bootstrap.min.css` (project mode)
  794. - License: `MIT`
  795. - License source: `https://raw.githubusercontent.com/twbs/bootstrap/v5.0.0/LICENSE`
  796. Bootstrap Icons builtin package details:
  797. - Package: `bootstrap-icons` (alias: `@bootstrap-icons`)
  798. - Bundled version: `1.11.3`
  799. - Asset kind: SVG sprite (`bootstrap-icons.svg`)
  800. - Default install location: `vendor/icons/bootstrap-icons.svg` (project mode)
  801. - License: `MIT`
  802. - License source: `https://raw.githubusercontent.com/twbs/icons/v1.11.3/LICENSE`
  803. Bootstrap notes:
  804. - Bootstrap is vendored and installable through the asset pipeline.
  805. - Bootstrap CSS is consumed as an explicit local asset (`--asset @bootstrap` or `AssetBundle`); external HTML `<link rel="stylesheet">` is not an execution path.
  806. - Bootstrap preflight examples remain useful smoke examples, but they are not the canonical source of CSS parity claims.
  807. ## Validated CSS Coverage
  808. For the full, maintained coverage statement, see `docs/css-coverage.md`.
  809. The retained full-corpus comparison of the qualified native-navigation work
  810. reports **1,625 PASS, 19 FAIL and 18 REFERENCE-DISPUTED** across 1,662 unchanged
  811. cases. The [independent run](https://github.com/fullbleed-engine/fullbleed-official/actions/runs/39933879568)
  812. keeps its failed all-pass conclusion. Two failures improve against published
  813. **2.6.0a13**, with no newly failing fixtures. All 29 output PNGs for the remaining
  814. 19 failures are byte-identical to that baseline. The
  815. [retained review](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/tools/pdf_link_readers/observations/link-candidate-corpus.json)
  816. records source, wheel and artifact identities. This is source-built Linux
  817. evidence; the [alpha 14 runbook](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/release/2.6.0a14-runbook.md)
  818. requires final-version qualification and public-package verification.
  819. This comparison does not establish complete CSS parity or conformance for
  820. arbitrary documents. Earlier dated results below are historical.
  821. Summary as of May 19, 2026:
  822. - Tracked CSS modules: `22`
  823. - Module state: `22/22 in_progress`
  824. - Full CSS fixture lane: `86/86` fixtures passing with `603` assertion/paint checks
  825. - Parity status check: green (`tools/generate_css_parity_status.py --check --json`)
  826. - Canonical validation artifact: `_css_working/css_parity_status.json`
  827. - Canonical validation artifact: `_css_working/tmp/fixture_full_latest.json`
  828. - Canonical validation artifact: `_css_working/css_broad_coverage_sprint_s14.md`
  829. The complete pinned independent Wheel265 gate closed on August 9, 2026 with `1,642 PASS`,
  830. `0 FAIL`, and `20 REFERENCE-DISPUTED` across 1,662 fixtures. That is strict `100%` parity for
  831. every adjudicable fixture in this named corpus; disputed references remain visible and are not
  832. relabeled as implementation passes. Broader web-platform coverage remains bounded by the module
  833. and known-gap contract in `docs/css-coverage.md`.
  834. Flow/reflow hardening validated on August 5, 2026 adds fixed-height block,
  835. one-column grid, and column-flex continuation slicing; avoids content
  836. duplication; retains empty styled captions inside avoided figures; preserves
  837. `display: contents` grid paint phase; and keeps positioned containing blocks
  838. atomic. The independent review's targeted 18-case regression cluster passes
  839. `18/18` (13 pixel-exact, maximum above-floor difference `0.97030199%`). This
  840. targeted diagnostic does not replace the full external-corpus report.
  841. Current validated behavior includes first-class parser -> evaluator -> calculator -> layout/paint coverage across broad static-document CSS domains (values math, layout primitives, pagination/fragmentation baselines, transforms phase-1, gradient/effects subsets including color-first and interleaved-color `filter: drop-shadow(...)` with computed lengths, modern `rgb()` shadow colors with `mm` lengths, duplicate `drop-shadow(...)` color rejection, empty optional filter-function defaults, explicit/currentColor `backdrop-filter: drop-shadow(...)` raster paint, strict `box-shadow` length/color grammar with modern `rgb()` plus `mm` paint coverage, softened blurred inset edge paint, and directional inset offset edge paint, overflow-gated `text-overflow: ellipsis`, physical min/max box constraints, horizontal-tb RTL `direction` inline inset/margin/padding/border mapping, vertical writing-mode `direction: rtl` inline inset remapping, vertical-rl logical sizing/insets/margin/padding/border/min-max constraints, vertical-lr logical sizing/min-max/insets/margin/padding/border remapping, basic vertical text columns with `vertical-rl` leftward and `vertical-lr` rightward line progression, and deterministic diagnostics).
  842. Known gap categories are explicitly tracked for the final parity push:
  843. - remaining filter/backdrop-filter function breadth beyond current subset, including SVG `url()` filters, advanced `drop-shadow()` forms beyond the current flexible-color-order foreground and baseline backdrop coverage, and PDF-native foreground filters
  844. - advanced `clip-path` grammar beyond the current basic-shape subset, including SVG clip sources, SVG-specific geometry boxes, and deeper edge grammar
  845. - plus-lighter PDF-native parity and deeper nested compositing/isolation breadth
  846. - deeper blurred inset shadow edge fidelity
  847. - remaining multi-layer background image edge semantics beyond the current sized gradient-layer repeat-x/space/round and PNG `url(...)` explicit-size/auto-auto-intrinsic/negative-size-invalid/contain/cover/auto-dimension-size/single-value-size/alpha-stack/default-repeat-repeat/repeat-y/repeat/repeat-no-repeat/no-repeat-repeat/space-space/round-round/round-space/space-round/round-repeat/round-no-repeat/no-repeat-round/no-repeat-space/space-no-repeat/repeat-space/repeat-round/space-repeat/logical-repeat-aliases/multi-layer-repeat-axis/background-list-repetition/percentage-position/edge-offset-position/logical-position-aliases/shorthand-position-size-repeat/content-box-origin-clip/multi-layer-origin-clip/background-blend-normal/background-blend-multiply/screen-mode/overlay-mode/exclusion-mode/hard-light-mode/darken-mode/lighten-mode/color-dodge-mode/color-burn-mode/soft-light-mode/hue-mode/saturation-mode/color-mode/luminosity-mode/plus-lighter-mode/list-repetition/truncation/raster-blend/raster-layer-mapping/mixed-raster-gradient-mapping/mixed-gradient-raster-mapping subset, including broader mixed raster stack combinations
  848. - table layout edge semantics hardening beyond the current fixed-layout width-hint, auto-width, caption-side placement, and invalid caption-side inheritance lanes
  849. - full vertical text/layout flow beyond the current vertical static-layout and basic wrapped text-column baseline
  850. ## `run` Command (Python Factory Interop)
  851. `run` lets the CLI use a Python-created engine instance.
  852. `report.py`:
  853. ```python
  854. import fullbleed
  855. def create_engine():
  856. return fullbleed.PdfEngine(page_width="8.5in", page_height="11in", margin="0.5in")
  857. ```
  858. CLI invocation:
  859. ```bash
  860. fullbleed --json run report:create_engine \
  861. --html-str "<h1>From run</h1>" \
  862. --css templates/report.css \
  863. --out output/report.pdf
  864. ```
  865. Entrypoint formats:
  866. - `module_name:factory_or_engine`
  867. - `path/to/file.py:factory_or_engine`
  868. ## Rust chart compilation
  869. For Rust-based visual/source frontends, the engine also provides
  870. [document-context chart compilation](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/chart-typography.md): normal CSS font
  871. selection and size, project-font legend measurement/wrapping, semantic tables,
  872. and observable layout failures. Generated SVG is derived output, not authoring
  873. source.
  874. ## Python API Quick Start
  875. ```python
  876. import fullbleed
  877. engine = fullbleed.PdfEngine(
  878. page_width="8.5in",
  879. page_height="11in",
  880. margin="0.5in",
  881. pdf_version="1.7",
  882. pdf_profile="none",
  883. color_space="rgb",
  884. )
  885. html = "<html><body><h1>Invoice</h1><p>Hello.</p></body></html>"
  886. css = "body { font-family: sans-serif; }"
  887. bytes_written = engine.render_pdf_to_file(html, css, "output/invoice.pdf")
  888. print(bytes_written)
  889. ```
  890. Register local assets with `AssetBundle`:
  891. ```python
  892. import fullbleed
  893. bundle = fullbleed.AssetBundle()
  894. bundle.add_file("vendor/css/bootstrap.min.css", "css", name="bootstrap")
  895. bundle.add_file("vendor/fonts/Inter-Variable.ttf", "font", name="inter")
  896. engine = fullbleed.PdfEngine(page_width="8.5in", page_height="11in")
  897. engine.register_bundle(bundle)
  898. engine.render_pdf_to_file("<h1>Styled</h1>", "", "output/styled.pdf")
  899. ```
  900. ## Python API Signatures (Runtime-Verified)
  901. These signatures are verified from the installed package via `inspect.signature(...)`.
  902. `PdfEngine` constructor:
  903. ```python
  904. PdfEngine(
  905. page_width=None,
  906. page_height=None,
  907. margin=None,
  908. page_margins=None,
  909. font_dirs=None,
  910. font_files=None,
  911. reuse_xobjects=True,
  912. svg_form_xobjects=False,
  913. svg_raster_fallback=False,
  914. unicode_support=True,
  915. shape_text=True,
  916. unicode_metrics=True,
  917. pdf_version=None,
  918. pdf_profile=None,
  919. output_intent_icc=None,
  920. output_intent_identifier=None,
  921. output_intent_info=None,
  922. output_intent_components=None,
  923. color_space=None,
  924. document_lang=None,
  925. document_title=None,
  926. header_first=None,
  927. header_each=None,
  928. header_last=None,
  929. header_x=None,
  930. header_y_from_top=None,
  931. header_font_name=None,
  932. header_font_size=None,
  933. header_color=None,
  934. header_html_first=None,
  935. header_html_each=None,
  936. header_html_last=None,
  937. header_html_x=None,
  938. header_html_y_from_top=None,
  939. header_html_width=None,
  940. header_html_height=None,
  941. footer_first=None,
  942. footer_each=None,
  943. footer_last=None,
  944. footer_x=None,
  945. footer_y_from_bottom=None,
  946. footer_font_name=None,
  947. footer_font_size=None,
  948. footer_color=None,
  949. watermark=None,
  950. watermark_text=None,
  951. watermark_html=None,
  952. watermark_image=None,
  953. watermark_layer="overlay",
  954. watermark_semantics="artifact",
  955. watermark_opacity=0.15,
  956. watermark_rotation=0.0,
  957. watermark_font_name=None,
  958. watermark_font_size=None,
  959. watermark_color=None,
  960. paginated_context=None,
  961. jit_mode=None,
  962. debug=False,
  963. debug_out=None,
  964. perf=False,
  965. perf_out=None,
  966. )
  967. ```
  968. For regular/italic family selection and exact face mappings, see
  969. [Registering fonts](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/font-registration.md).
  970. Module exports:
  971. - `PdfEngine`
  972. - `CompiledDocument`
  973. - `CompiledFlowCompression`
  974. - `AssetBundle`
  975. - `Asset`
  976. - `AssetKind`
  977. - `WatermarkSpec(kind, value, layer='overlay', semantics=None, opacity=0.15, rotation_deg=0.0, font_name=None, font_size=None, color=None)`
  978. - `concat_css(parts)`
  979. - `vendored_asset(source, kind, name=None, trusted=False, remote=False)`
  980. - `inspect_pdf(path)`
  981. - `inspect_template_catalog(templates)`
  982. - `finalize_stamp_pdf(template, overlay, out, page_map=None, dx=0.0, dy=0.0)`
  983. - `finalize_compose_pdf(templates, plan, overlay, out, annotation_mode='link_only')`
  984. - `fetch_asset(url)`
  985. `PdfEngine` methods:
  986. | Method | Return shape |
  987. | --- | --- |
  988. | `register_bundle(bundle)` | `None` |
  989. | `compile_pdf(html, css)` | `CompiledDocument` |
  990. | `render_pdf(html, css, deterministic_hash=None)` | `bytes` |
  991. | `render_pdf_to_file(html, css, path, deterministic_hash=None)` | `int` (bytes written) |
  992. | `render_image_pages(html, css, dpi=150)` | `list[bytes]` |
  993. | `render_image_pages_to_dir(html, css, out_dir, dpi=150, stem=None)` | `list[str]` |
  994. | `render_finalized_pdf_image_pages(pdf_path, dpi=150)` | `list[bytes]` |
  995. | `render_finalized_pdf_image_pages_to_dir(pdf_path, out_dir, dpi=150, stem=None)` | `list[str]` |
  996. | `render_pdf_with_glyph_report(html, css)` | `(bytes, list)` |
  997. | `render_pdf_with_page_data(html, css)` | `(bytes, page_data_or_none)` |
  998. | `render_pdf_with_page_data_and_glyph_report(html, css)` | `(bytes, page_data_or_none, glyph_report_list)` |
  999. | `render_pdf_with_page_data_and_template_bindings(html, css)` | `(bytes, page_data_or_none, template_bindings_or_none)` |
  1000. | `render_pdf_with_page_data_and_template_bindings_and_glyph_report(html, css)` | `(bytes, page_data_or_none, template_bindings_or_none, glyph_report_list)` |
  1001. | `plan_template_compose(html, css, templates, dx=0.0, dy=0.0)` | `dict` |
  1002. | `render_pdf_batch(html_list, css, deterministic_hash=None)` | `bytes` |
  1003. | `render_pdf_batch_parallel(html_list, css, deterministic_hash=None)` | `bytes` |
  1004. | `render_pdf_batch_to_file(html_list, css, path, deterministic_hash=None)` | `int` |
  1005. | `render_pdf_batch_to_file_parallel(html_list, css, path, deterministic_hash=None)` | `int` |
  1006. | `render_pdf_batch_to_file_parallel_with_page_data(html_list, css, path, deterministic_hash=None)` | `(bytes_written, page_data_list)` |
  1007. | `render_pdf_batch_with_css(jobs, deterministic_hash=None)` | `bytes` |
  1008. | `render_pdf_batch_with_css_to_file(jobs, path, deterministic_hash=None)` | `int` |
  1009. `CompiledDocument` methods:
  1010. | Method | Return shape |
  1011. | --- | --- |
  1012. | `stats()` | `dict` |
  1013. | `render_pdf(deterministic_hash=None)` | `bytes` |
  1014. | `render_pdf_to_file(path, deterministic_hash=None)` | `int` |
  1015. | `render_pdf_batch(copies, deterministic_hash=None)` | `bytes` |
  1016. | `render_pdf_bindings(bindings, deterministic_hash=None)` | `bytes` |
  1017. | `render_pdf_bindings_with_report(bindings, deterministic_hash=None)` | `(bytes, report)` |
  1018. | `render_pdf_bindings_to_file(bindings, path, deterministic_hash=None)` | `int` |
  1019. | `render_pdf_reflow_bindings(bindings, deterministic_hash=None, *, compression="throughput")` | `bytes` |
  1020. | `render_pdf_reflow_bindings_with_report(bindings, deterministic_hash=None, *, compression="throughput")` | `(bytes, report)` |
  1021. | `render_pdf_reflow_bindings_to_file(bindings, path, deterministic_hash=None, *, compression="throughput")` | `int` |
  1022. The `*_with_report` methods return ordered record page ranges and missing-character checks
  1023. against the registered fonts selected for the final text. Reports preserve PDF bytes and
  1024. reuse the compiled layout. See [compiled batch reports](https://github.com/fullbleed-engine/fullbleed-official/blob/master/docs/python-api.md#check-a-compiled-batch-before-accepting-it)
  1025. for acceptance checks and coverage limits.
  1026. The compiled lane runs parsing/layout once. `render_pdf_batch` virtualizes identical untagged page
  1027. content. The fixed binding methods accept columnar `dict[str, list[str]]` data and emit distinct
  1028. fixed-geometry text overlays per record while sharing static paint. They require exact slot keys,
  1029. equal non-zero column lengths, page-local text, and an untagged profile. Base-14 text uses the
  1030. direct byte-patch lane; registered fonts are shaped into a command-level overlay. Bound values do
  1031. not trigger layout or reflow.
  1032. The reflow binding methods use the same exact-column contract but execute the compiled parsed-DOM
  1033. program. `{{slot}}` values are literal text and may reshape, wrap, resize blocks, and change page
  1034. counts. Empty elements can opt into trusted generated markup with
  1035. `data-fb-bind-html="slot"`; those values replace the element's children. One DOM is reused per
  1036. native worker and record output is linked in input order through a bounded queue. Structural slot
  1037. values are parsed as trusted markup: sanitize untrusted input or use scalar `{{slot}}` bindings,
  1038. which remain literal text. Choose `CompiledFlowCompression.Throughput` (default) or
  1039. `CompiledFlowCompression.Compact` per render; modes can be mixed safely in one process. See
  1040. [`docs/python-api.md`](https://github.com/fullbleed-engine/fullbleed-official/blob/v2.6.0a14/docs/python-api.md) for the trust boundary and current limitations.
  1041. When `deterministic_hash` is set, engine writes PDF SHA-256 to the provided file path.
  1042. `AssetBundle` methods:
  1043. - `add_file(path, kind, name=None, trusted=False, remote=False)`
  1044. - `add(asset)`
  1045. - `assets_info()`
  1046. - `css()`
  1047. ## Python Examples (Smoke-Checked)
  1048. Canonical scaffold reference:
  1049. ```bash
  1050. python examples/canonical_reference/report.py
  1051. ```
  1052. Text watermark + diagnostics:
  1053. ```python
  1054. import fullbleed
  1055. engine = fullbleed.PdfEngine(
  1056. page_width="8.5in",
  1057. page_height="11in",
  1058. margin="0.5in",
  1059. pdf_version="1.7",
  1060. watermark_text="INTERNAL",
  1061. watermark_layer="overlay",
  1062. watermark_semantics="artifact",
  1063. watermark_opacity=0.12,
  1064. watermark_rotation=-32.0,
  1065. debug=True,
  1066. debug_out="build/invoice.jit.jsonl",
  1067. perf=True,
  1068. perf_out="build/invoice.perf.jsonl",
  1069. )
  1070. html = "<h1>Invoice</h1><p>Status: Ready</p>"
  1071. css = "h1{margin:0 0 8px 0} p{margin:0}"
  1072. written = engine.render_pdf_to_file(html, css, "output/invoice_watermarked.pdf")
  1073. print("bytes:", written)
  1074. ```
  1075. Batch render + glyph/page-data checks:
  1076. ```python
  1077. import fullbleed
  1078. engine = fullbleed.PdfEngine(page_width="8.5in", page_height="11in", margin="0.5in")
  1079. jobs = [
  1080. ("<h1>Batch A</h1><p>Alpha</p>", "h1{color:#0d6efd}"),
  1081. ("<h1>Batch B</h1><p>Beta</p>", "h1{color:#198754}"),
  1082. ]
  1083. written = engine.render_pdf_batch_with_css_to_file(jobs, "output/batch.pdf")
  1084. print("batch bytes:", written)
  1085. pdf_bytes, glyph_report = engine.render_pdf_with_glyph_report("<p>Hello</p>", "")
  1086. print("glyph entries:", len(glyph_report))
  1087. pdf_bytes, page_data = engine.render_pdf_with_page_data("<p>Hello</p>", "")
  1088. print("page data available:", page_data is not None)
  1089. ```
  1090. ## Transactional Header/Footer + Totals
  1091. Minimal, self-contained Python example (no external template files) showing:
  1092. - Continued headers on page 2+.
  1093. - Per-page subtotal footer expansion via `{sum:items.amount}`.
  1094. - Final-page grand total footer expansion via `{total:items.amount}`.
  1095. - Structured `page_data` totals for automation and reconciliation checks.
  1096. ```python
  1097. from pathlib import Path
  1098. import fullbleed
  1099. rows = []
  1100. for i in range(1, 121): # enough rows to force multiple pages
  1101. amount = 10.00 + ((i * 7) % 23) + 0.25
  1102. rows.append(
  1103. f'<tr data-fb="items.amount={amount:.2f}">'
  1104. f"<td>2026-01-{(i % 28) + 1:02d}</td>"
  1105. f"<td>Txn {i:03d}</td>"
  1106. f'<td class="num">${amount:.2f}</td>'
  1107. "</tr>"
  1108. )
  1109. html = f"""<!doctype html>
  1110. <html>
  1111. <body>
  1112. <h1>Monthly Statement</h1>
  1113. <table>
  1114. <thead>
  1115. <tr><th>Date</th><th>Description</th><th class="num">Amount</th></tr>
  1116. </thead>
  1117. <tbody>
  1118. {''.join(rows)}
  1119. </tbody>
  1120. </table>
  1121. </body>
  1122. </html>
  1123. """
  1124. css = """
  1125. body { font-family: sans-serif; font-size: 10pt; color: #111; }
  1126. h1 { margin: 0 0 8pt 0; }
  1127. table { width: 100%; border-collapse: collapse; }
  1128. th, td { padding: 4pt; border-bottom: 1pt solid #e1e1e1; }
  1129. thead th { background: #f3f6fa; text-transform: uppercase; font-size: 9pt; }
  1130. .num { text-align: right; }
  1131. """
  1132. engine = fullbleed.PdfEngine(
  1133. page_width="8.5in",
  1134. page_height="11in",
  1135. margin="12mm",
  1136. page_margins={
  1137. 1: {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  1138. 2: {"top": "28mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  1139. "n": {"top": "28mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  1140. },
  1141. header_html_each=(
  1142. '<div style="display:flex;justify-content:space-between;border-bottom:1pt solid #d9d9d9;">'
  1143. '<div style="font-weight:bold;">Acme Ledger</div>'
  1144. '<div style="font-size:9pt;color:#444;">Statement Continued - Page {page} of {pages}</div>'
  1145. "</div>"
  1146. ),
  1147. header_html_x="12mm",
  1148. header_html_y_from_top="6mm",
  1149. header_html_width="186mm",
  1150. header_html_height="10mm",
  1151. paginated_context={"items.amount": "sum"},
  1152. footer_each="Subtotal (Page {page}): ${sum:items.amount}",
  1153. footer_last="Grand Total: ${total:items.amount}",
  1154. footer_x="12mm",
  1155. footer_y_from_bottom="8mm",
  1156. )
  1157. pdf_bytes, page_data = engine.render_pdf_with_page_data(html, css)
  1158. Path("output_transactional_minimal.pdf").write_bytes(pdf_bytes)
  1159. assert page_data["page_count"] >= 2
  1160. assert page_data["totals"]["items.amount"]["value"] == sum(
  1161. p["items.amount"]["value"] for p in page_data["pages"]
  1162. )
  1163. print("Wrote output_transactional_minimal.pdf")
  1164. print("Page count:", page_data["page_count"])
  1165. print("Grand total:", page_data["totals"]["items.amount"]["formatted"])
  1166. ```
  1167. API note:
  1168. - For transactional running totals (`paginated_context`) and HTML header/footer placement (`header_html_*`, `footer_html_*`), use the Python `PdfEngine` API path.
  1169. - The CLI currently exposes direct text header/footer flags (`--header-each`, `--footer-each`) for simpler cases.
  1170. CLI watermark parity example:
  1171. ```bash
  1172. fullbleed --json render \
  1173. --html-str "<h1>Watermark probe</h1><p>hello</p>" \
  1174. --css-str "body{font-family:sans-serif}" \
  1175. --watermark-text "INTERNAL" \
  1176. --watermark-layer overlay \
  1177. --watermark-opacity 0.12 \
  1178. --watermark-rotation -32 \
  1179. --out output/watermark_probe.pdf
  1180. ```
  1181. ## Reference-Image Parity Workflow (Practical)
  1182. When targeting a design reference image (for example reference image exports), this loop has worked well:
  1183. 1. Start from `fullbleed init` so CSS/font/icon baselines are vendored and pinned.
  1184. 2. For scaffolded projects, run `python report.py` and set `FULLBLEED_IMAGE_DPI` as needed for sharper previews.
  1185. 3. For direct CLI template rendering, register assets through the CLI (`--asset ...`) or `AssetBundle`.
  1186. 4. Iterate with image artifacts enabled:
  1187. ```bash
  1188. fullbleed --json render \
  1189. --profile preflight \
  1190. --html templates/invoice.html \
  1191. --css templates/invoice.css \
  1192. --asset vendor/css/bootstrap.min.css --asset-kind css --asset-name bootstrap \
  1193. --asset vendor/icons/bootstrap-icons.svg --asset-kind svg --asset-name bootstrap-icons \
  1194. --asset vendor/fonts/Inter-Variable.ttf --asset-kind font --asset-name inter \
  1195. --emit-image output/pages_png \
  1196. --emit-jit output/render.jit.jsonl \
  1197. --emit-perf output/render.perf.jsonl \
  1198. --out output/render.pdf
  1199. ```
  1200. 5. Use `--repro-record` / `--repro-check` once your layout stabilizes.
  1201. Practical tips:
  1202. - Compare against full-page exports when available.
  1203. - Keep a fixed preview DPI (for example `144` or `200`) across iterations.
  1204. - Commit PNG baselines for repeatable visual checks.
  1205. ## Public Golden Regression Suite
  1206. Launch-grade render regression coverage is available under `goldens/` with three fixtures:
  1207. - `invoice`
  1208. - `statement`
  1209. - `menu`
  1210. Golden contract assets:
  1211. - Expected hashes: `goldens/expected/golden_suite.expected.json`
  1212. - Expected PNG baselines: `goldens/expected/png/<case>/<case>_page1.png`
  1213. Run against committed expectations:
  1214. ```bash
  1215. python goldens/run_golden_suite.py verify
  1216. ```
  1217. Refresh baselines intentionally:
  1218. ```bash
  1219. python goldens/run_golden_suite.py generate
  1220. ```
  1221. ## Human + AI Operating Mode
  1222. Recommended automation defaults:
  1223. ```bash
  1224. fullbleed --json-only render ...
  1225. ```
  1226. Why this is agent-safe:
  1227. - For command-execution JSON payloads, `schema` is always present.
  1228. - Parser usage errors (`exit=2`) are emitted by argparse as usage text, not JSON payloads.
  1229. - `ok` indicates success/failure without parsing text.
  1230. - Optional artifacts are explicitly named in `outputs`.
  1231. - Schema introspection is available at runtime (`--schema`).
  1232. Example parse loop:
  1233. ```python
  1234. import json, subprocess
  1235. proc = subprocess.run(
  1236. [
  1237. "fullbleed", "--json-only", "render",
  1238. "--html", "templates/report.html",
  1239. "--css", "templates/report.css",
  1240. "--out", "output/report.pdf",
  1241. ],
  1242. capture_output=True,
  1243. text=True,
  1244. check=False,
  1245. )
  1246. payload = json.loads(proc.stdout)
  1247. assert payload["schema"] == "fullbleed.render_result.v1"
  1248. assert payload["ok"] is True
  1249. print(payload["outputs"]["pdf"])
  1250. ```
  1251. ## MACHINE_CONTRACT.v1
  1252. ```json
  1253. {
  1254. "schema": "fullbleed.readme_contract.v1",
  1255. "package": "fullbleed",
  1256. "cli_entrypoint": "fullbleed",
  1257. "dev_cli_entrypoint": "python -m fullbleed_cli.cli",
  1258. "python_module": "fullbleed",
  1259. "json_discriminator": "schema",
  1260. "core_commands": [
  1261. "render",
  1262. "verify",
  1263. "plan",
  1264. "debug-perf",
  1265. "debug-jit",
  1266. "run",
  1267. "finalize",
  1268. "inspect",
  1269. "compliance",
  1270. "doctor",
  1271. "capabilities",
  1272. "assets",
  1273. "cache",
  1274. "init",
  1275. "new"
  1276. ],
  1277. "result_schemas": [
  1278. "fullbleed.render_result.v1",
  1279. "fullbleed.verify_result.v1",
  1280. "fullbleed.plan_result.v1",
  1281. "fullbleed.run_result.v1",
  1282. "fullbleed.inspect_pdf.v1",
  1283. "fullbleed.inspect_pdf_batch.v1",
  1284. "fullbleed.inspect_templates.v1",
  1285. "fullbleed.compose_plan.v1",
  1286. "fullbleed.compliance.v1",
  1287. "fullbleed.capabilities.v1",
  1288. "fullbleed.doctor.v1",
  1289. "fullbleed.assets_list.v1",
  1290. "fullbleed.assets_info.v1",
  1291. "fullbleed.assets_install.v1",
  1292. "fullbleed.assets_verify.v1",
  1293. "fullbleed.assets_lock.v1",
  1294. "fullbleed.cache_dir.v1",
  1295. "fullbleed.cache_prune.v1",
  1296. "fullbleed.init.v1",
  1297. "fullbleed.new_template.v1",
  1298. "fullbleed.new_list.v1",
  1299. "fullbleed.new_search.v1",
  1300. "fullbleed.new_remote.v1",
  1301. "fullbleed.debug_perf.v1",
  1302. "fullbleed.debug_jit.v1",
  1303. "fullbleed.repro_record.v1",
  1304. "fullbleed.error.v1"
  1305. ],
  1306. "artifact_flags": [
  1307. "--emit-manifest",
  1308. "--emit-jit",
  1309. "--emit-perf",
  1310. "--emit-glyph-report",
  1311. "--emit-page-data",
  1312. "--emit-compose-plan",
  1313. "--emit-image",
  1314. "--image-dpi",
  1315. "--deterministic-hash",
  1316. "--repro-record",
  1317. "--repro-check"
  1318. ],
  1319. "fail_on": ["overflow", "missing-glyphs", "font-subst", "budget"],
  1320. "budget_flags": ["--budget-max-pages", "--budget-max-bytes", "--budget-max-ms"],
  1321. "profiles": ["dev", "preflight", "prod"],
  1322. "pdf_version_default": "1.7",
  1323. "known_exit_codes": {
  1324. "0": "success",
  1325. "1": "command-level validation/operational failure",
  1326. "2": "argparse usage error",
  1327. "3": "CLI runtime/input error wrapper"
  1328. }
  1329. }
  1330. ```
  1331. ## Important Behavior Notes
  1332. - `render --json` cannot be combined with `--out -` (stdout PDF bytes).
  1333. - `verify` defaults to stdout PDF unless `--emit-pdf` is provided; for machine mode, use `--emit-pdf <path>`.
  1334. - `--emit-image <dir>` writes per-page PNGs as `<stem>_pageN.png` (stem comes from `--out`/`--emit-pdf`, or `render` when streaming PDF to stdout).
  1335. - In template auto-compose runs, `--emit-image` artifacts are rasterized from finalized composed pages and report `outputs.image_mode=composed_pdf`; otherwise `image_mode=overlay_document`.
  1336. - `outputs.deterministic_hash_mode` is `pdf_only` by default and `artifact_set_v1` when image artifacts are emitted.
  1337. - If both `--emit-page-data` and `--emit-glyph-report` are set, current engines use a combined API and render once; older engines without that API fall back to a double render.
  1338. - Production target is PDF `1.7`.
  1339. - `run` accepts `--html-str` without requiring `--html`.
  1340. - `init` now scaffolds `COMPLIANCE.md` for project-level release review.
  1341. - `compliance --json` emits machine-readable legal/procurement diagnostics.
  1342. - `--watermark-layer underlay` is accepted as a legacy alias and normalized to `background`.
  1343. - `--emit-manifest` includes a `watermark` object with `text|html|image|layer|semantics|opacity|rotation|enabled`.
  1344. - `--fail-on overflow` is enforced from placement data and may auto-enable internal JIT planning.
  1345. - `--fail-on font-subst` is enforced using missing glyph and fallback diagnostics.
  1346. - `--allow-fallbacks` allows fallback diagnostics to remain informational for `missing-glyphs` / `font-subst` gates while still reporting them in JSON output.
  1347. - `--fail-on budget` requires at least one budget threshold flag.
  1348. - `--repro-check` fails on input/hash drift and lock hash mismatches when lock data is available.
  1349. - PDF/A and PDF/X/VT profiles require output intent metadata; `pdfa4`, `pdfa4e`, and `pdfa4f` emit PDF 2.0 automatically. PDF/A, PDF/X/VT, PDF/UA, and WTPDF text output enforces embedded-font constraints, and CLI errors include an actionable hint to add an embeddable font asset.
  1350. - `--pdf-profile pdfua1` enables tagged output and PDF/UA-1 identification metadata. Treat verifier/seed traces as machine evidence before making external conformance claims.
  1351. - `argparse` usage errors exit with code `2` and emit usage text (not JSON), even when `--json` is present.
  1352. ## Related Docs
  1353. - Agent workflow guide: `llm.txt`
  1354. - CLI JSON contract quick reference: `cli_schema.md`
  1355. - CLI epoch/spec: `CLI_EPOCH.md`
  1356. - PDF template/XObject composition guide: `docs/pdf-templates.md`
  1357. - Licensing guide: `LICENSING.md`
  1358. - Third-party notices: `THIRD_PARTY_LICENSES.md`
  1359. - Living docs example project: `examples/living_docs_atlas/README.md`
  1360. - Roofing invoice parity example: `examples/roofing_invoice/README.md`
  1361. - Iconography smoke example: `examples/iconography_test/README.md`
  1362. - Public golden regression suite: `goldens/README.md`
  1363. ## License
  1364. Fullbleed is licensed under the MIT License (`MIT`). Commercial use,
  1365. modification, distribution, and use in proprietary software are permitted
  1366. subject to the notice-preservation requirement in `LICENSE`.
  1367. Cargo and PyPI metadata both declare `MIT`.
  1368. - Copyright notice: `COPYRIGHT`
  1369. - Third-party notices: `THIRD_PARTY_LICENSES.md`
  1370. - Practical licensing guide: `LICENSING.md`
  1371. For license information, please visit `fullbleed.dev` or email `info@fullbleed.dev`.
  1372. License integrity gate (CI-friendly, no build required):
  1373. ```bash
  1374. python tools/check_license_integrity.py --json
  1375. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.