{
  "markdown": "<!-- SPDX-License-Identifier: MIT -->\n# Fullbleed PDF Engine\n\nFullbleed 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.\n\nIt 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.\n\n\nLicense: MIT.\n\n\n\n- **Install:** `pip install fullbleed`\n- **Try:** `fullbleed init . && python report.py`\n- **Discover:** `fullbleed agent-contract --format json`\n- **Outputs:** `output/report.pdf` \n- Deterministic + reproducible (`--repro-record` / `--repro-check`)\n- Agent-safe JSON schemas (`--json-only`, `--schema`)\n\n## Positioning\n\nFullbleed 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).\n\nHTML and CSS are used as a familiar DSL for layout, styling, and data placement in transactional documents.\n\n## Agent discovery and integrations\n\nAn 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:\n\n```bash\nfullbleed agent-manifest --json\n# Equivalent canonical form:\nfullbleed agent-contract --format json\n```\n\nThe committed [`fullbleed-agent-contract.json`](fullbleed-agent-contract.json), [`cli_schema.md`](cli_schema.md), and [`llms.txt`](llms.txt) are generated from the built wheel. CI rejects version, command, schema, profile, or capability drift. Runtime introspection remains authoritative.\n\nThe first-party, versionless [`skills/fullbleed/SKILL.md`](skills/fullbleed/SKILL.md) teaches tool selection and the render/preview/diagnose/verify loop without duplicating the manual. It is bundled in the wheel and can be exported into any absent or empty agent-skill directory:\n\n```bash\nfullbleed agent skill-path --json\nfullbleed agent export-skill .agents/skills/fullbleed --json\n```\n\nFor tool-calling agents, install the separately versioned adapter so the core package remains dependency-free:\n\n```bash\npython -m pip install fullbleed-mcp\nfullbleed-mcp --root .\n```\n\nThe 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 .`.\n\nUse 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.\n\nCold-agent testing is available through `fullbleed agent-acceptance`; compact copyable workflows live in [`examples/agent_workflows`](examples/agent_workflows), and the approach-neutral benchmark scaffold lives in [`agentdocbench`](agentdocbench).\n\n\nThis README is the canonical usage guide for:\n\n- `fullbleed` CLI (human workflows + machine/agent automation)\n- `fullbleed` Python bindings (`PdfEngine`, `AssetBundle`, batch APIs)\n\nAdditional focused references are in `docs/`:\n\n- `docs/install-non-technical.md` (step-by-step setup for non-technical users)\n- `docs/css-coverage.md` (validated CSS coverage, parity status, and active gaps)\n- `docs/README.md`\n- `docs/engine.md`\n- `docs/performance-architecture.md`\n- `docs/performance-pass-2026-08-04.md`\n- `docs/python-api.md`\n- `docs/ui-accessibility.md`\n- `docs/cli.md`\n- `docs/pdf-templates.md`\n\n## What You Get\n\n- No headless browser requirement for PDF generation.\n- Deterministic render pipeline with optional SHA256 output hashing.\n- Reproducibility workflow via `--repro-record` and `--repro-check`.\n- PDF `1.7` as the production-stable default target.\n- Rust-native PDF template composition for VDP/transactional overlays.\n- Native Rust image emission for overlay and finalized compose outputs (`--emit-image`) without external PDF raster runtime dependencies.\n- Feature-driven page-to-template binding with per-page deterministic compose plans.\n- Structured JSON result schemas for CI and AI agents.\n- Offline-first asset model with explicit remote opt-in.\n- Remote project template registry workflows (`new list`, `new search`, `new remote`).\n- Python-first extension surface for hackability and custom workflows.\n- Python render calls release the GIL while Rust rendering executes.\n- Ordered standard-library worker pools for batch rendering and selected internal workloads.\n- A deliberately small, license-audited Rust dependency graph and no required third-party Python\n  runtime or build packages.\n\n## Concurrency Model\n\n- Python binding render methods release the GIL during Rust execution through the Stable ABI bridge.\n- Parallel batch APIs use Fullbleed's ordered standard-library worker pool (`render_pdf_batch_parallel(...)` and parallel-to-file variants).\n- The same bounded worker implementation serves selected internal hotspots such as table layout and JIT paint paths.\n- Do not assume every single-document render path will fully saturate all cores end-to-end.\n\n## Performance in 2.2\n\nFullbleed 2.2 retains exact TrueType glyph subsetting and adds compiled fixed-geometry variable-data\nbinding. Across the five independent benchmark fixtures, PDFs are 95.5-97.3% smaller and ordinary\nwarm rendering is 2.90x faster by geometric mean than released 2.0.0.\n\nThe new compile-once API freezes an immutable Q32.32 display document and can link it repeatedly\nwithout rerunning HTML parsing, selector matching, layout, pagination, or command planning. For\nidentical untagged copies in one ordered PDF, `CompiledDocument.render_pdf_batch(...)` shares each\nsource page's content stream across the copied page dictionaries. The measured 20-copy lane is\n200.7x faster per page by geometric mean than the released 2.0.0 warm renderer; a 1,000-page stress\nrun sustained 304,479-666,622 pages/s.\n\nThe 2.2 compiler includes a genuine fixed-geometry variable-data lane. A compiled invoice\nwith six bound fields rendered 100,000 distinct records in a five-run median of 283.807 ms to\nmemory (**352,352 pages/s**) and 295.999 ms directly to a flushed 88.1 MB PDF\n(**337,839 pages/s**). Including the one-time 4.168 ms compile gives 333,147 direct-file pages/s.\nThe harness verified all 100,000 unique invoice IDs in page order, exact page count, resolved\nmarkers, deterministic bytes, and equal buffer/file SHA-256. Reproduce it with:\n\n```bash\npython tools/benchmark_fullbleed_vdp.py --records 100000 --repeats 5\n```\n\nFixed-geometry slots may remain inside immutable page-space transforms and clips. The compiler\ncaptures that active coordinate-state program once and replays it in each compact record overlay;\nit does not rerun layout or clone the complete page display list.\n\nBase-14/WinAnsi slot paint keeps the measured byte-patch linker. Registered embedded fonts use a\ncommand-level overlay program so each bound value is shaped and included in the font subset while\nthe compiled layout, pagination, and static page stream remain shared. The throughput figures above\ndescribe the Base-14 fast lane; they are not claims for registered-font shaping.\n\nThe fixed-copy result remains scoped to identical content; the variable-data result is scoped to\npaint-only text whose geometry does not reflow. Neither is a claim that arbitrary new HTML or\nsize-changing records render 200x faster. See\n[`docs/performance-pass-2026-08-04.md`](docs/performance-pass-2026-08-04.md) for measurements and\n[`docs/performance-architecture.md`](docs/performance-architecture.md) for the packed vector IR,\ntyped-binding, virtual-linker, and shader roadmap.\n\nFullbleed 2.2.5 hardens the third compiler lane introduced in 2.2.4 for\nsize-changing records: `CompiledDocument.render_pdf_reflow_bindings(...)`. It parses and recovers\nthe template DOM once and compiles encountered structural flow variants into guarded fixed-point\ndisplay programs. Matching records bind directly into those programs; workers execute pre-shaped\ntext/TJ paint slots, cached static PDF page segments, page-local Deflate, and one ordered linker.\nExplicit trusted structural slots use `data-fb-bind-html=\"slot\"`. A value that no compiled variant\ncan safely place runs ordinary fixed-point layout once to add another variant.\n\nOn the independent 1,000-distinct-record case study, the 29-sample hot direct-file median was\n216.160 ms: **4,626 records/s and 8,096 pages/s**. The 168.995 ms best sample reached **5,917\nrecords/s and 10,355 pages/s**. It produced\nthe exact 1,750-page 500/300/150/50 reflow distribution and verified all 24,900 markers. The\nthroughput-tuned 6,870,320-byte PDF was deterministic across all samples. With the compact\ncompression setting, compiled output was also byte-for-byte identical to ordinary rendering:\n5,298,961 bytes and SHA-256 `bb3c441313a08fb00d3bd15f23a567981f3bbbd550908e3a9fe7a07ca5d7f138`.\nThis is a hot compiled-variant result, not a claim for previously unseen structure. The first\nvariant-discovery render measured 0.509 s (3,437 pages/s), and the fully cold job including setup,\nbindings, compilation, discovery, and write measured 0.588 s (2,975 pages/s). The independently\nobserved hot-median speedup over the ordinary path was 43.8x.\n\n## Install\n\nNew to Python or setting up on a fresh machine? Start with `docs/install-non-technical.md`.\n\n```bash\npython -m pip install fullbleed\n```\n\nFrom a local wheel:\n\n```bash\npython -m pip install C:\\path\\to\\fullbleed-2.3.1-cp310-abi3-win_amd64.whl\n```\n\nFrom a source checkout with Rust installed, no Python build package is needed:\n\n```bash\npython -m pip install --no-build-isolation --no-deps --editable .\n```\n\nTo create deterministic release artifacts directly:\n\n```bash\npython build_backend/fullbleed_build_backend.py wheel --out dist\npython build_backend/fullbleed_build_backend.py sdist --out dist\n```\n\nPlatform artifact policy:\n\n- Linux wheels cover `manylinux2014` on x86-64, x86, ARM64, ARMv7, s390x,\n  and ppc64le, plus `musllinux_1_2` on x86-64, x86, ARM64, and ARMv7.\n- Windows wheels cover x86-64, x86, and ARM64; macOS wheels cover Intel and\n  Apple silicon.\n- The CPython stable ABI allows each platform wheel to support Python 3.10\n  through 3.14.\n- CI installs and exercises every built wheel on its target architecture,\n  using native runners or QEMU as appropriate. The x86-64 manylinux wheel is\n  additionally tested on every supported Python version before publication.\n\nVerify command surface:\n\n```bash\nfullbleed --help\nfullbleed capabilities --json\nfullbleed doctor --json\n```\n\n## 60-Second Quick Start (Project Happy Path)\n\nInitialize project scaffold:\n\n```bash\nfullbleed init .\n```\n\n`fullbleed init` now vendors Bootstrap (`5.0.0`) into `vendor/css/bootstrap.min.css`,\nvendors Bootstrap Icons (`1.11.3`) into `vendor/icons/bootstrap-icons.svg`,\nvendors `inter` into `vendor/fonts/Inter-Variable.ttf`, writes license notices\n(`vendor/css/LICENSE.bootstrap.txt`, `vendor/icons/LICENSE.bootstrap-icons.txt`, `vendor/fonts/LICENSE.inter.txt`),\nand seeds `assets.lock.json` with pinned hashes.\nThe scaffolded `report.py` also runs a component mount smoke validation before\nmain render and writes `output/component_mount_validation.json` (fails fast on\nmissing glyphs, actual pagination overflow, or CSS miss signals). On current engines,\nrender-time pagination is authoritative for overflow; conservative JIT placement bounds\nremain the compatibility fallback for older engines.\nScaffolded components now include `components/primitives.py` with reusable\nlayout/content helpers (`Stack`, `Row`, `Text`, table/list helpers, key/value rows, etc.).\nEach scaffolded project also includes `SCAFFOLDING.md`, which should be your\nfirst read before restructuring components.\nIt also includes `AGENTS.md`, which preserves the installed-runtime-first\ndocument workflow across future coding-agent sessions without making other\ndocument tools categorically forbidden.\n\nInstall additional project assets (defaults to `./vendor/...` in project context):\n\n```bash\nfullbleed assets install inter --json\n```\n\nBootstrap baseline note:\n- We target Bootstrap (`5.0.0`) as the default styling baseline for project workflows.\n- Re-run `fullbleed assets install bootstrap --json` only if you want to explicitly refresh/bootstrap-manage outside `init`.\n\nRender using the scaffolded component pipeline:\n\n```bash\npython report.py\n```\n\nExpected artifacts from scaffolded `report.py`:\n- `output/report.pdf`\n- `output/report_page1.png` (or equivalent page preview from engine image APIs)\n- `output/component_mount_validation.json`\n- `output/css_layers.json`\n\nCanonical static PDF reference:\n\n```bash\npython examples/canonical_reference/report.py\n```\n\n`examples/canonical_reference/` is the exhaustive scaffold-shaped reference for\ncomponent composition, layered CSS, bundled fonts/SVG, inline SVG, raster data\nURIs, linked and standalone HTML artifacts, PDF output, PNG previews, and\nvalidation reports.\n\n## Project Bootstrap Templates (`fullbleed new`)\n\nUse local starters:\n\n```bash\nfullbleed new local invoice ./my-invoice\nfullbleed new local statement ./my-statement\nfullbleed new local accessible ./my-accessible-doc\nfullbleed new local reference ./my-reference-doc\n```\n\nDiscover remote starters from registry:\n\n```bash\nfullbleed new list --json\nfullbleed new search i9 --tag vdp --json\nfullbleed new remote i9-stamped-vdp ./i9-job --json\n```\n\n`fullbleed new local accessible` is the verbose accessibility-first starter and\ndemonstrates the `fullbleed.accessibility` runtime surface (engine verifier,\nPMR, PDF/UA-targeted seed checks, and non-visual trace artifacts).\n`fullbleed new local reference` vendors the canonical static PDF reference shape\nas a scaffolded project with component layers, assets, PDF/PNG outputs, page data,\nand validation reports.\n\nOptional registry override (for private/canary registries):\n\n```bash\nfullbleed new list --registry https://example.com/manifest.json --json\n```\n\nor:\n\n```bash\nset FULLBLEED_TEMPLATE_REGISTRY=https://example.com/manifest.json\nfullbleed new search statement --json\n```\n\n## Scaffold-First Workflow (Recommended)\n\n`fullbleed init` is designed for component-first authoring rather than a single large HTML template.\n\nTypical scaffold layout:\n\n```text\n.\n|-- SCAFFOLDING.md\n|-- COMPLIANCE.md\n|-- report.py\n|-- components/\n|   |-- fb_ui.py\n|   |-- primitives.py\n|   |-- header.py\n|   |-- body.py\n|   |-- footer.py\n|   `-- styles/\n|       |-- primitives.css\n|       |-- header.css\n|       |-- body.css\n|       `-- footer.css\n|-- styles/\n|   |-- tokens.css\n|   `-- report.css\n|-- vendor/\n|   |-- css/\n|   |-- fonts/\n|   `-- icons/\n`-- output/\n```\n\nBest-practice authoring model:\n1. Read `SCAFFOLDING.md` first for project conventions.\n2. Keep composition and data loading in `report.py`.\n3. Keep reusable component building blocks in `components/primitives.py`.\n4. Keep section markup in `components/header.py`, `components/body.py`, `components/footer.py`.\n5. Keep component-local styles in `components/styles/*.css`.\n6. Keep page tokens/composition styles in `styles/tokens.css` and `styles/report.css`.\n\nRecommended CSS layer order:\n1. `styles/tokens.css`\n2. `components/styles/primitives.css`\n3. `components/styles/header.css`\n4. `components/styles/body.css`\n5. `components/styles/footer.css`\n6. `styles/report.css`\n\nRecommended iteration loop:\n1. Edit data loading + component props in `report.py`.\n2. Edit component markup in `components/*.py`.\n3. Edit styles in `components/styles/*.css` and `styles/*.css`.\n4. Run `python report.py`.\n5. Review `output/report_page1.png`, `output/component_mount_validation.json`, and `output/css_layers.json`.\n\nOptional scaffold diagnostics:\n- `FULLBLEED_DEBUG=1` to emit JIT traces.\n- `FULLBLEED_PERF=1` to emit perf traces.\n- `FULLBLEED_EMIT_PAGE_DATA=1` to persist page data JSON.\n- `FULLBLEED_IMAGE_DPI=144` (or higher) for preview resolution.\n- `FULLBLEED_VALIDATE_STRICT=1` for stricter validation gates in CI.\n\n## One-off Quick Render (No Project Scaffold)\n\nRender inline HTML/CSS with reproducibility artifacts:\n\n```bash\nfullbleed --json render \\\n  --html-str \"<html><body><h1>Hello</h1></body></html>\" \\\n  --css-str \"body{font-family:sans-serif}\" \\\n  --emit-manifest build/render.manifest.json \\\n  --emit-jit build/render.jit.jsonl \\\n  --emit-perf build/render.perf.jsonl \\\n  --deterministic-hash build/render.sha256 \\\n  --repro-record build/render.repro.json \\\n  --out output/hello.pdf\n```\n\n`--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.\n\nRe-run and enforce reproducibility against a stored record:\n\n```bash\nfullbleed --json render \\\n  --html templates/report.html \\\n  --css templates/report.css \\\n  --repro-check build/render.repro.json \\\n  --out output/report.rerun.pdf\n```\n\nGenerate PNG page artifacts from an existing validation render:\n\n```bash\nfullbleed --json verify \\\n  --html templates/report.html \\\n  --css templates/report.css \\\n  --emit-pdf output/report.verify.pdf \\\n  --emit-image output/report_verify_pages \\\n  --image-dpi 200\n```\n\nCompile-only plan (no render):\n\n```bash\nfullbleed --json plan \\\n  --html templates/report.html \\\n  --css templates/report.css\n```\n\nTemplate compose planning (no finalize write):\n\n```bash\nfullbleed --json plan \\\n  --html templates/overlay.html \\\n  --css templates/overlay.css \\\n  --template-binding config/template_binding.json \\\n  --templates config/template_catalog.json \\\n  --emit-compose-plan output/compose_plan.json\n```\n\n## PDF Template Composition (VDP / Transactional)\n\nWhen overlaying variable data onto a source PDF, use the built-in Rust template compose path.\n\nMinimal CLI auto-compose flow:\n\n```bash\nfullbleed --json render \\\n  --html templates/overlay.html \\\n  --css templates/overlay.css \\\n  --asset templates/source.pdf --asset-kind pdf --asset-name source-template \\\n  --template-binding config/template_binding.json \\\n  --templates config/template_catalog.json \\\n  --out output/composed.pdf\n```\n\nCompose image semantics:\n- In template auto-compose mode, `--emit-image` PNGs are rasterized from finalized composed pages and report `outputs.image_mode=composed_pdf`.\n- In non-compose `render`/`verify` runs, `--emit-image` reports `outputs.image_mode=overlay_document`.\n\nMinimal `template_binding` example:\n\n```json\n{\n  \"default_template_id\": \"source-template\",\n  \"feature_prefix\": \"fb.feature.\",\n  \"by_feature\": {\n    \"front\": \"source-template\",\n    \"back_blank\": \"source-template\"\n  }\n}\n```\n\nPython API compose flow:\n\n```python\nimport fullbleed\n\nengine = fullbleed.PdfEngine(template_binding=binding_spec)\noverlay_bytes, _page_data, _bindings = engine.render_pdf_with_page_data_and_template_bindings(html, css)\nopen(\"output/overlay.pdf\", \"wb\").write(overlay_bytes)\nplan_result = engine.plan_template_compose(\n    html,\n    css,\n    [(\"source-template\", \"templates/source.pdf\")],\n    0.0,\n    0.0,\n)\nplan = [\n    (\n        row[\"template_id\"],\n        row[\"template_page\"],\n        row[\"overlay_page\"],\n        row[\"dx\"],\n        row[\"dy\"],\n    )\n    for row in plan_result[\"plan\"]\n]\nfullbleed.finalize_compose_pdf(\n    [(\"source-template\", \"templates/source.pdf\")],\n    plan,\n    \"output/overlay.pdf\",\n    \"output/composed.pdf\",\n    annotation_mode=\"link_only\",  # optional: link_only | none | carry_widgets\n)\n```\n\nSee `docs/pdf-templates.md` and `examples/template-flagging-smoke/` for full production examples.\n\n## CLI Command Map\n\n| Command | Purpose | JSON Schema |\n| --- | --- | --- |\n| `render` | Render HTML/CSS to PDF with optional PNG page artifacts | `fullbleed.render_result.v1` |\n| `verify` | Validation render path with optional PDF and PNG emits | `fullbleed.verify_result.v1` |\n| `plan` | Compile/normalize inputs into manifest + warnings | `fullbleed.plan_result.v1` |\n| `run` | Render using Python module/file engine factory | `fullbleed.run_result.v1` |\n| `inspect pdf` | Inspect PDF metadata and composition compatibility | `fullbleed.inspect_pdf.v1` |\n| `inspect pdf-batch` | Inspect multiple PDFs with per-file status | `fullbleed.inspect_pdf_batch.v1` |\n| `inspect templates` | Inspect template catalog metadata/compatibility | `fullbleed.inspect_templates.v1` |\n| `compliance` | License/compliance report for legal/procurement | `fullbleed.compliance.v1` |\n| `debug-perf` | Summarize perf JSONL logs | `fullbleed.debug_perf.v1` |\n| `debug-jit` | Filter/inspect JIT JSONL logs | `fullbleed.debug_jit.v1` |\n| `doctor` | Runtime capability and health checks | `fullbleed.doctor.v1` |\n| `capabilities` | Machine-readable command/engine capabilities | `fullbleed.capabilities.v1` |\n| `assets list` | Installed and optional remote packages | `fullbleed.assets_list.v1` |\n| `assets info` | Package details + hashes/sizes | `fullbleed.assets_info.v1` |\n| `assets install` | Install builtin/remote package | `fullbleed.assets_install.v1` |\n| `assets verify` | Validate package and optional lock constraints | `fullbleed.assets_verify.v1` |\n| `assets lock` | Write/update `assets.lock.json` | `fullbleed.assets_lock.v1` |\n| `cache dir` | Cache location | `fullbleed.cache_dir.v1` |\n| `cache prune` | Remove old cached packages | `fullbleed.cache_prune.v1` |\n| `init` | Initialize project scaffold | `fullbleed.init.v1` |\n| `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` |\n\nSchema discovery for any command/subcommand:\n\n```bash\nfullbleed --schema render\nfullbleed --schema assets verify\nfullbleed --schema inspect pdf\nfullbleed --schema inspect templates\n```\n\n## CLI Flags That Matter Most\n\nGlobal machine flags:\n\n- `--json`: structured result payload to stdout\n- `--json-only`: implies `--json` and `--no-prompts`\n- `--schema`: emit schema definition and exit\n- `--no-prompts`: disable interactive prompts\n- `--config`: load defaults from a config file\n- `--log-level error|warn|info|debug`: control CLI log verbosity\n- `--no-color`: disable ANSI color output\n- `--version`: print CLI version and exit\n\nRender/verify/plan key flags:\n\n- Inputs: `--html`, `--html-str`, `--css`, `--css-str`\n  `--html` accepts `.svg` files for direct SVG-document rendering; `--html-str` accepts inline SVG markup.\n- Page setup: `--page-size`, `--page-width`, `--page-height`, `--margin`, `--page-margins`\n- Engine toggles: `--reuse-xobjects`, `--svg-form-xobjects`, `--svg-raster-fallback`, `--shape-text`, `--unicode-support`, `--unicode-metrics`\n- PDF/compliance: `--pdf-version`, `--pdf-profile`, `--color-space`, `--document-lang`, `--document-title`\n  Stable default is `--pdf-version 1.7` for shipping workflows.\n  Profile targets: `none`, `pdfa1a`, `pdfa1b`, `pdfa2a`, `pdfa2b`, `pdfa2u`, `pdfa3a`, `pdfa3b`, `pdfa3u`, `pdfa4`, `pdfa4e`, `pdfa4f`, `pdfx4`, `pdfua1`, `pdfua2`, `pdfvt1`, `wtpdf1r`, `wtpdf1a`, `tagged`.\n  Aliases: `a`, `ua`, `vt`, `wt1r`, `wt1a`, `pdf/a`, `pdf/ua`, `pdf/vt`.\n  Output intent metadata (`--output-intent-identifier|--output-intent-info|--output-intent-components`) requires `--output-intent-icc`.\n  Run `python tools/validate_pdf_profiles.py --download-verapdf --install-pdf-oxide --strict-external`\n  to regenerate profile specimens, capture inspect/JIT evidence, replay\n  deterministic hashes, validate PDF/A and PDF/UA with veraPDF, and validate\n  PDF/X-4 with `pdf_oxide`. WTPDF profiles are validated with veraPDF\n  `wt1r`/`wt1a` and include PDF Declaration evidence. `pdfa4f` emits and\n  checks an associated `EmbeddedFiles` name tree. `pdfvt1` also emits and checks a parsed\n  DPart graph (`DPartRoot`, `DPartRootNode`, one-level `NodeNameList`, leaf page range,\n  and page `/DPart` references), including a supplemental multipage specimen\n  for `/Start` and `/End`, reported as granular booleans plus\n  `pdfvt_dpart_graph_valid`; use a dedicated PDF/VT preflight tool\n  for third-party PDF/VT certification, or wire one into the same harness with\n  `--pdfvt-cmd \"tool --input {pdf}\" --require-dedicated-pdfvt`.\n- Watermarking: `--watermark-text`, `--watermark-html`, `--watermark-image`, `--watermark-layer`, `--watermark-semantics`, `--watermark-opacity`, `--watermark-rotation`\n- Artifacts: `--emit-jit`, `--emit-perf`, `--emit-glyph-report`, `--emit-page-data`, `--emit-compose-plan`, `--emit-image`, `--image-dpi`, `--deterministic-hash`\n- Assets: `--asset`, `--asset-kind`, `--asset-name`, `--asset-trusted`, `--allow-remote-assets`\n- Profiles: `--profile dev|preflight|prod`\n- Fail policy: `--fail-on overflow|missing-glyphs|font-subst|budget`\n- Fallback policy: `--allow-fallbacks` (keeps fallback diagnostics, but does not fail `missing-glyphs` / `font-subst` gates)\n- Reproducibility: `--repro-record <path>`, `--repro-check <path>`\n- Budget thresholds: `--budget-max-pages`, `--budget-max-bytes`, `--budget-max-ms`\n- Release gates: `doctor --strict`, `compliance --strict --max-audit-age-days <n>`\n\n## SVG Workflows\n\nFullbleed supports SVG in three practical CLI paths:\n\n- Direct SVG document render via `--html <file.svg>`\n- Inline SVG markup via `--html-str \"<svg ...>...</svg>\"`\n- Referenced SVG assets via `--asset <file.svg>` (kind auto-infers to `svg`)\n\nStandalone SVG file to PDF:\n\n```bash\nfullbleed --json render \\\n  --html artwork/badge.svg \\\n  --out output/badge.pdf\n```\n\nInline SVG markup to PDF:\n\n```bash\nfullbleed --json render \\\n  --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>\" \\\n  --out output/inline-svg.pdf\n```\n\nHTML template with explicit SVG asset registration:\n\n```bash\nfullbleed --json render \\\n  --html templates/report.html \\\n  --css templates/report.css \\\n  --asset assets/logo.svg \\\n  --asset-kind svg \\\n  --out output/report.pdf\n```\n\nSVG render behavior flags:\n\n- `--svg-form-xobjects` / `--no-svg-form-xobjects`\n- `--svg-raster-fallback` / `--no-svg-raster-fallback`\n\nDistributed Python wheels enable the `svg_raster` engine feature, so\n`--svg-raster-fallback` can rasterize unsupported SVG constructs such as SVG\ntext, filters, masks, and `foreignObject` into deterministic image content.\nCustom source builds must include `--features python,svg_raster` to advertise\nand use that fallback path.\n\nMachine discovery:\n\n```bash\nfullbleed capabilities --json\n```\n\nInspect the `svg` object in `fullbleed.capabilities.v1` for SVG support metadata. The `engine`\nobject also reports compiled-document/reflow availability and supported per-call compression modes.\nIt reports the compiled `svg_raster` build feature plus a feature matrix for\nnative-vector SVG, raster-fallback-required SVG, and unsupported/known-loss SVG\nfeatures.\n\n## Image Support Matrix\n\nLaunch-safe image claims:\n\n- Supported direct raster inputs: PNG and JPEG.\n- SVG is handled by the SVG pipeline described above, with native-vector output\n  where supported and raster fallback for fallback-only features when\n  `svg_raster` is enabled.\n- Supported references include filesystem paths, registered bundle assets,\n  file/data URIs, `<img>`, CSS `background-image: url(...)`, list-style images,\n  and watermark images.\n- Unsupported or not launch-claimed as direct inputs: WebP, GIF, TIFF, AVIF,\n  BMP, animated images, `<picture>`, `srcset`, `sizes`, density descriptors,\n  and browser-style responsive image selection.\n- For deterministic builds, prefer vendored local assets or registered\n  `AssetBundle` inputs; remote assets must be explicitly allowed.\n\n## Per-Page Templates (`page_1`, `page_2`, `page_n`)\n\nFullbleed uses ordered page templates internally. In docs, this is easiest to think of as:\n\n- `page_1`: first page template\n- `page_2`: second page template\n- `page_n`: repeating template for later pages\n\nConfiguration mapping:\n\n- CLI `--page-margins` keys: `1`, `2`, ... and optional `\"n\"` (or `\"each\"` alias).\n- Python `PdfEngine(page_margins=...)`: same key model.\n- Missing numeric pages fall back to the base `margin`.\n- The last configured template repeats for remaining pages.\n\nMinimal CLI example:\n\n```json\n{\n  \"1\": {\"top\": \"12mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"},\n  \"2\": {\"top\": \"24mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"},\n  \"n\": {\"top\": \"30mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"}\n}\n```\n\n```bash\nfullbleed --json render \\\n  --html templates/report.html \\\n  --css templates/report.css \\\n  --page-margins page_margins.json \\\n  --header-each \"Statement continued - Page {page} of {pages}\" \\\n  --out output/report.pdf\n```\n\nMinimal Python example:\n\n```python\nimport fullbleed\n\nengine = fullbleed.PdfEngine(\n    page_width=\"8.5in\",\n    page_height=\"11in\",\n    margin=\"12mm\",\n    page_margins={\n        1: {\"top\": \"12mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"},  # page_1\n        2: {\"top\": \"24mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"},  # page_2\n        \"n\": {\"top\": \"30mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"} # page_n\n    },\n    header_first=\"Account Statement\",\n    header_each=\"Statement continued - Page {page} of {pages}\",\n    footer_last=\"Final page\",\n)\n```\n\nNote:\n- CLI currently exposes `--header-each` / `--footer-each` (and `--header-html-each` / `--footer-html-each`).\n- For `first/last` header/footer variants (`header_first`, `header_last`, `footer_first`, `footer_last`), use the Python API.\n\n## Asset Workflow (CLI)\n\nList installed + available packages:\n\n```bash\nfullbleed assets list --available --json\n```\n\nInstall builtin assets:\n\n```bash\nfullbleed assets install bootstrap\nfullbleed assets install bootstrap-icons\n# `@bootstrap` / `@bootstrap-icons` are also supported aliases\n```\n\nPowerShell note:\n- Quote `@` aliases (for example `\"@bootstrap\"`) to avoid shell parsing surprises.\n\nInstall remote asset package:\n\n```bash\nfullbleed assets install inter\n```\n\nInstall broad Unicode fallback package (larger font payload):\n\n```bash\nfullbleed assets install noto-sans\n```\n\nInstall to a custom vendor directory:\n\n```bash\nfullbleed assets install bootstrap --vendor ./vendor\n```\n\nInstall to global cache:\n\n```bash\nfullbleed assets install inter --global\n```\n\nInstall common barcode fonts (license-safe defaults):\n\n```bash\nfullbleed assets install libre-barcode-128\nfullbleed assets install libre-barcode-39\nfullbleed assets install libre-barcode-ean13-text\n```\n\nVerify against lock file with strict failure:\n\n```bash\nfullbleed assets verify inter --lock --strict --json\n```\n\nPreview cache cleanup without deleting files:\n\n```bash\nfullbleed cache prune --max-age-days 30 --dry-run --json\n```\n\nNotes:\n\n- Builtin packages accept both plain and `@` references (`bootstrap` == `@bootstrap`, `bootstrap-icons` == `@bootstrap-icons`, `noto-sans` == `@noto-sans`).\n- `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.\n- Project installs default to `./vendor/` when project markers are present (`assets.lock.json`, `report.py`, or `fullbleed.toml` in CWD).\n- If no project markers are found, `assets install` defaults to global cache unless `--vendor` is explicitly set.\n- Do not hardcode cache paths like `%LOCALAPPDATA%/fullbleed/cache/...`; use `assets install --json` and consume `installed_to`.\n- Installed assets include license files in typed vendor directories (for example `vendor/fonts/`, `vendor/css/`).\n- `assets lock --add` is currently aimed at builtin package additions.\n- Barcode packages in the remote registry are currently OFL-1.1 families from Google Fonts (`Libre Barcode`).\n- USPS IMB fonts are not currently auto-installable via `assets install`; use local vetted font files and track licensing separately.\n\n## Bootstrap Vendoring\n\nBootstrap builtin package details:\n\n- Package: `bootstrap` (alias: `@bootstrap`)\n- Bundled version: `5.0.0`\n- Asset kind: CSS (`bootstrap.min.css`)\n- Default install location: `vendor/css/bootstrap.min.css` (project mode)\n- License: `MIT`\n- License source: `https://raw.githubusercontent.com/twbs/bootstrap/v5.0.0/LICENSE`\n\nBootstrap Icons builtin package details:\n\n- Package: `bootstrap-icons` (alias: `@bootstrap-icons`)\n- Bundled version: `1.11.3`\n- Asset kind: SVG sprite (`bootstrap-icons.svg`)\n- Default install location: `vendor/icons/bootstrap-icons.svg` (project mode)\n- License: `MIT`\n- License source: `https://raw.githubusercontent.com/twbs/icons/v1.11.3/LICENSE`\n\nBootstrap notes:\n\n- Bootstrap is vendored and installable through the asset pipeline.\n- Bootstrap CSS is consumed as an explicit local asset (`--asset @bootstrap` or `AssetBundle`); external HTML `<link rel=\"stylesheet\">` is not an execution path.\n- Bootstrap preflight examples remain useful smoke examples, but they are not the canonical source of CSS parity claims.\n\n## Validated CSS Coverage\n\nFor the full, maintained coverage statement, see `docs/css-coverage.md`.\n\nSummary as of May 19, 2026:\n\n- Tracked CSS modules: `22`\n- Module state: `22/22 in_progress`\n- Full CSS fixture lane: `86/86` fixtures passing with `603` assertion/paint checks\n- Parity status check: green (`tools/generate_css_parity_status.py --check --json`)\n- Canonical validation artifact: `_css_working/css_parity_status.json`\n- Canonical validation artifact: `_css_working/tmp/fixture_full_latest.json`\n- Canonical validation artifact: `_css_working/css_broad_coverage_sprint_s14.md`\n\nThe complete pinned independent Wheel265 gate closed on August 9, 2026 with `1,642 PASS`,\n`0 FAIL`, and `20 REFERENCE-DISPUTED` across 1,662 fixtures. That is strict `100%` parity for\nevery adjudicable fixture in this named corpus; disputed references remain visible and are not\nrelabeled as implementation passes. Broader web-platform coverage remains bounded by the module\nand known-gap contract in `docs/css-coverage.md`.\n\nFlow/reflow hardening validated on August 5, 2026 adds fixed-height block,\none-column grid, and column-flex continuation slicing; avoids content\nduplication; retains empty styled captions inside avoided figures; preserves\n`display: contents` grid paint phase; and keeps positioned containing blocks\natomic. The independent review's targeted 18-case regression cluster passes\n`18/18` (13 pixel-exact, maximum above-floor difference `0.97030199%`). This\ntargeted diagnostic does not replace the full external-corpus report.\n\nCurrent 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).\n\nKnown gap categories are explicitly tracked for the final parity push:\n\n- 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\n- advanced `clip-path` grammar beyond the current basic-shape subset, including SVG clip sources, SVG-specific geometry boxes, and deeper edge grammar\n- plus-lighter PDF-native parity and deeper nested compositing/isolation breadth\n- deeper blurred inset shadow edge fidelity\n- 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\n- table layout edge semantics hardening beyond the current fixed-layout width-hint, auto-width, caption-side placement, and invalid caption-side inheritance lanes\n- full vertical text/layout flow beyond the current vertical static-layout and basic wrapped text-column baseline\n\n## `run` Command (Python Factory Interop)\n\n`run` lets the CLI use a Python-created engine instance.\n\n`report.py`:\n\n```python\nimport fullbleed\n\ndef create_engine():\n    return fullbleed.PdfEngine(page_width=\"8.5in\", page_height=\"11in\", margin=\"0.5in\")\n```\n\nCLI invocation:\n\n```bash\nfullbleed --json run report:create_engine \\\n  --html-str \"<h1>From run</h1>\" \\\n  --css templates/report.css \\\n  --out output/report.pdf\n```\n\nEntrypoint formats:\n\n- `module_name:factory_or_engine`\n- `path/to/file.py:factory_or_engine`\n\n## Python API Quick Start\n\n```python\nimport fullbleed\n\nengine = fullbleed.PdfEngine(\n    page_width=\"8.5in\",\n    page_height=\"11in\",\n    margin=\"0.5in\",\n    pdf_version=\"1.7\",\n    pdf_profile=\"none\",\n    color_space=\"rgb\",\n)\n\nhtml = \"<html><body><h1>Invoice</h1><p>Hello.</p></body></html>\"\ncss = \"body { font-family: sans-serif; }\"\n\nbytes_written = engine.render_pdf_to_file(html, css, \"output/invoice.pdf\")\nprint(bytes_written)\n```\n\nRegister local assets with `AssetBundle`:\n\n```python\nimport fullbleed\n\nbundle = fullbleed.AssetBundle()\nbundle.add_file(\"vendor/css/bootstrap.min.css\", \"css\", name=\"bootstrap\")\nbundle.add_file(\"vendor/fonts/Inter-Variable.ttf\", \"font\", name=\"inter\")\n\nengine = fullbleed.PdfEngine(page_width=\"8.5in\", page_height=\"11in\")\nengine.register_bundle(bundle)\nengine.render_pdf_to_file(\"<h1>Styled</h1>\", \"\", \"output/styled.pdf\")\n```\n\n## Python API Signatures (Runtime-Verified)\n\nThese signatures are verified from the installed package via `inspect.signature(...)`.\n\n`PdfEngine` constructor:\n\n```python\nPdfEngine(\n    page_width=None,\n    page_height=None,\n    margin=None,\n    page_margins=None,\n    font_dirs=None,\n    font_files=None,\n    reuse_xobjects=True,\n    svg_form_xobjects=False,\n    svg_raster_fallback=False,\n    unicode_support=True,\n    shape_text=True,\n    unicode_metrics=True,\n    pdf_version=None,\n    pdf_profile=None,\n    output_intent_icc=None,\n    output_intent_identifier=None,\n    output_intent_info=None,\n    output_intent_components=None,\n    color_space=None,\n    document_lang=None,\n    document_title=None,\n    header_first=None,\n    header_each=None,\n    header_last=None,\n    header_x=None,\n    header_y_from_top=None,\n    header_font_name=None,\n    header_font_size=None,\n    header_color=None,\n    header_html_first=None,\n    header_html_each=None,\n    header_html_last=None,\n    header_html_x=None,\n    header_html_y_from_top=None,\n    header_html_width=None,\n    header_html_height=None,\n    footer_first=None,\n    footer_each=None,\n    footer_last=None,\n    footer_x=None,\n    footer_y_from_bottom=None,\n    footer_font_name=None,\n    footer_font_size=None,\n    footer_color=None,\n    watermark=None,\n    watermark_text=None,\n    watermark_html=None,\n    watermark_image=None,\n    watermark_layer=\"overlay\",\n    watermark_semantics=\"artifact\",\n    watermark_opacity=0.15,\n    watermark_rotation=0.0,\n    watermark_font_name=None,\n    watermark_font_size=None,\n    watermark_color=None,\n    paginated_context=None,\n    jit_mode=None,\n    debug=False,\n    debug_out=None,\n    perf=False,\n    perf_out=None,\n)\n```\n\nModule exports:\n\n- `PdfEngine`\n- `CompiledDocument`\n- `CompiledFlowCompression`\n- `AssetBundle`\n- `Asset`\n- `AssetKind`\n- `WatermarkSpec(kind, value, layer='overlay', semantics=None, opacity=0.15, rotation_deg=0.0, font_name=None, font_size=None, color=None)`\n- `concat_css(parts)`\n- `vendored_asset(source, kind, name=None, trusted=False, remote=False)`\n- `inspect_pdf(path)`\n- `inspect_template_catalog(templates)`\n- `finalize_stamp_pdf(template, overlay, out, page_map=None, dx=0.0, dy=0.0)`\n- `finalize_compose_pdf(templates, plan, overlay, out, annotation_mode='link_only')`\n- `fetch_asset(url)`\n\n`PdfEngine` methods:\n\n| Method | Return shape |\n| --- | --- |\n| `register_bundle(bundle)` | `None` |\n| `compile_pdf(html, css)` | `CompiledDocument` |\n| `render_pdf(html, css, deterministic_hash=None)` | `bytes` |\n| `render_pdf_to_file(html, css, path, deterministic_hash=None)` | `int` (bytes written) |\n| `render_image_pages(html, css, dpi=150)` | `list[bytes]` |\n| `render_image_pages_to_dir(html, css, out_dir, dpi=150, stem=None)` | `list[str]` |\n| `render_finalized_pdf_image_pages(pdf_path, dpi=150)` | `list[bytes]` |\n| `render_finalized_pdf_image_pages_to_dir(pdf_path, out_dir, dpi=150, stem=None)` | `list[str]` |\n| `render_pdf_with_glyph_report(html, css)` | `(bytes, list)` |\n| `render_pdf_with_page_data(html, css)` | `(bytes, page_data_or_none)` |\n| `render_pdf_with_page_data_and_glyph_report(html, css)` | `(bytes, page_data_or_none, glyph_report_list)` |\n| `render_pdf_with_page_data_and_template_bindings(html, css)` | `(bytes, page_data_or_none, template_bindings_or_none)` |\n| `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)` |\n| `plan_template_compose(html, css, templates, dx=0.0, dy=0.0)` | `dict` |\n| `render_pdf_batch(html_list, css, deterministic_hash=None)` | `bytes` |\n| `render_pdf_batch_parallel(html_list, css, deterministic_hash=None)` | `bytes` |\n| `render_pdf_batch_to_file(html_list, css, path, deterministic_hash=None)` | `int` |\n| `render_pdf_batch_to_file_parallel(html_list, css, path, deterministic_hash=None)` | `int` |\n| `render_pdf_batch_to_file_parallel_with_page_data(html_list, css, path, deterministic_hash=None)` | `(bytes_written, page_data_list)` |\n| `render_pdf_batch_with_css(jobs, deterministic_hash=None)` | `bytes` |\n| `render_pdf_batch_with_css_to_file(jobs, path, deterministic_hash=None)` | `int` |\n\n`CompiledDocument` methods:\n\n| Method | Return shape |\n| --- | --- |\n| `stats()` | `dict` |\n| `render_pdf(deterministic_hash=None)` | `bytes` |\n| `render_pdf_to_file(path, deterministic_hash=None)` | `int` |\n| `render_pdf_batch(copies, deterministic_hash=None)` | `bytes` |\n| `render_pdf_bindings(bindings, deterministic_hash=None)` | `bytes` |\n| `render_pdf_bindings_to_file(bindings, path, deterministic_hash=None)` | `int` |\n| `render_pdf_reflow_bindings(bindings, deterministic_hash=None, *, compression=\"throughput\")` | `bytes` |\n| `render_pdf_reflow_bindings_to_file(bindings, path, deterministic_hash=None, *, compression=\"throughput\")` | `int` |\n\nThe compiled lane runs parsing/layout once. `render_pdf_batch` virtualizes identical untagged page\ncontent. The fixed binding methods accept columnar `dict[str, list[str]]` data and emit distinct\nfixed-geometry text overlays per record while sharing static paint. They require exact slot keys,\nequal non-zero column lengths, page-local text, and an untagged profile. Base-14 text uses the\ndirect byte-patch lane; registered fonts are shaped into a command-level overlay. Bound values do\nnot trigger layout or reflow.\n\nThe reflow binding methods use the same exact-column contract but execute the compiled parsed-DOM\nprogram. `{{slot}}` values are literal text and may reshape, wrap, resize blocks, and change page\ncounts. Empty elements can opt into trusted generated markup with\n`data-fb-bind-html=\"slot\"`; those values replace the element's children. One DOM is reused per\nnative worker and record output is linked in input order through a bounded queue. Structural slot\nvalues are parsed as trusted markup: sanitize untrusted input or use scalar `{{slot}}` bindings,\nwhich remain literal text. Choose `CompiledFlowCompression.Throughput` (default) or\n`CompiledFlowCompression.Compact` per render; modes can be mixed safely in one process. See\n[`docs/python-api.md`](docs/python-api.md) for the trust boundary and current limitations.\n\nWhen `deterministic_hash` is set, engine writes PDF SHA-256 to the provided file path.\n\n`AssetBundle` methods:\n\n- `add_file(path, kind, name=None, trusted=False, remote=False)`\n- `add(asset)`\n- `assets_info()`\n- `css()`\n\n## Python Examples (Smoke-Checked)\n\nCanonical scaffold reference:\n\n```bash\npython examples/canonical_reference/report.py\n```\n\nText watermark + diagnostics:\n\n```python\nimport fullbleed\n\nengine = fullbleed.PdfEngine(\n    page_width=\"8.5in\",\n    page_height=\"11in\",\n    margin=\"0.5in\",\n    pdf_version=\"1.7\",\n    watermark_text=\"INTERNAL\",\n    watermark_layer=\"overlay\",\n    watermark_semantics=\"artifact\",\n    watermark_opacity=0.12,\n    watermark_rotation=-32.0,\n    debug=True,\n    debug_out=\"build/invoice.jit.jsonl\",\n    perf=True,\n    perf_out=\"build/invoice.perf.jsonl\",\n)\n\nhtml = \"<h1>Invoice</h1><p>Status: Ready</p>\"\ncss = \"h1{margin:0 0 8px 0} p{margin:0}\"\n\nwritten = engine.render_pdf_to_file(html, css, \"output/invoice_watermarked.pdf\")\nprint(\"bytes:\", written)\n```\n\nBatch render + glyph/page-data checks:\n\n```python\nimport fullbleed\n\nengine = fullbleed.PdfEngine(page_width=\"8.5in\", page_height=\"11in\", margin=\"0.5in\")\n\njobs = [\n    (\"<h1>Batch A</h1><p>Alpha</p>\", \"h1{color:#0d6efd}\"),\n    (\"<h1>Batch B</h1><p>Beta</p>\", \"h1{color:#198754}\"),\n]\n\nwritten = engine.render_pdf_batch_with_css_to_file(jobs, \"output/batch.pdf\")\nprint(\"batch bytes:\", written)\n\npdf_bytes, glyph_report = engine.render_pdf_with_glyph_report(\"<p>Hello</p>\", \"\")\nprint(\"glyph entries:\", len(glyph_report))\n\npdf_bytes, page_data = engine.render_pdf_with_page_data(\"<p>Hello</p>\", \"\")\nprint(\"page data available:\", page_data is not None)\n```\n\n## Transactional Header/Footer + Totals\n\nMinimal, self-contained Python example (no external template files) showing:\n\n- Continued headers on page 2+.\n- Per-page subtotal footer expansion via `{sum:items.amount}`.\n- Final-page grand total footer expansion via `{total:items.amount}`.\n- Structured `page_data` totals for automation and reconciliation checks.\n\n```python\nfrom pathlib import Path\nimport fullbleed\n\nrows = []\nfor i in range(1, 121):  # enough rows to force multiple pages\n    amount = 10.00 + ((i * 7) % 23) + 0.25\n    rows.append(\n        f'<tr data-fb=\"items.amount={amount:.2f}\">'\n        f\"<td>2026-01-{(i % 28) + 1:02d}</td>\"\n        f\"<td>Txn {i:03d}</td>\"\n        f'<td class=\"num\">${amount:.2f}</td>'\n        \"</tr>\"\n    )\n\nhtml = f\"\"\"<!doctype html>\n<html>\n<body>\n  <h1>Monthly Statement</h1>\n  <table>\n    <thead>\n      <tr><th>Date</th><th>Description</th><th class=\"num\">Amount</th></tr>\n    </thead>\n    <tbody>\n      {''.join(rows)}\n    </tbody>\n  </table>\n</body>\n</html>\n\"\"\"\n\ncss = \"\"\"\nbody { font-family: sans-serif; font-size: 10pt; color: #111; }\nh1 { margin: 0 0 8pt 0; }\ntable { width: 100%; border-collapse: collapse; }\nth, td { padding: 4pt; border-bottom: 1pt solid #e1e1e1; }\nthead th { background: #f3f6fa; text-transform: uppercase; font-size: 9pt; }\n.num { text-align: right; }\n\"\"\"\n\nengine = fullbleed.PdfEngine(\n    page_width=\"8.5in\",\n    page_height=\"11in\",\n    margin=\"12mm\",\n    page_margins={\n        1: {\"top\": \"12mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"},\n        2: {\"top\": \"28mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"},\n        \"n\": {\"top\": \"28mm\", \"right\": \"12mm\", \"bottom\": \"12mm\", \"left\": \"12mm\"},\n    },\n    header_html_each=(\n        '<div style=\"display:flex;justify-content:space-between;border-bottom:1pt solid #d9d9d9;\">'\n        '<div style=\"font-weight:bold;\">Acme Ledger</div>'\n        '<div style=\"font-size:9pt;color:#444;\">Statement Continued - Page {page} of {pages}</div>'\n        \"</div>\"\n    ),\n    header_html_x=\"12mm\",\n    header_html_y_from_top=\"6mm\",\n    header_html_width=\"186mm\",\n    header_html_height=\"10mm\",\n    paginated_context={\"items.amount\": \"sum\"},\n    footer_each=\"Subtotal (Page {page}): ${sum:items.amount}\",\n    footer_last=\"Grand Total: ${total:items.amount}\",\n    footer_x=\"12mm\",\n    footer_y_from_bottom=\"8mm\",\n)\n\npdf_bytes, page_data = engine.render_pdf_with_page_data(html, css)\nPath(\"output_transactional_minimal.pdf\").write_bytes(pdf_bytes)\n\nassert page_data[\"page_count\"] >= 2\nassert page_data[\"totals\"][\"items.amount\"][\"value\"] == sum(\n    p[\"items.amount\"][\"value\"] for p in page_data[\"pages\"]\n)\nprint(\"Wrote output_transactional_minimal.pdf\")\nprint(\"Page count:\", page_data[\"page_count\"])\nprint(\"Grand total:\", page_data[\"totals\"][\"items.amount\"][\"formatted\"])\n```\n\nAPI note:\n- For transactional running totals (`paginated_context`) and HTML header/footer placement (`header_html_*`, `footer_html_*`), use the Python `PdfEngine` API path.\n- The CLI currently exposes direct text header/footer flags (`--header-each`, `--footer-each`) for simpler cases.\n\nCLI watermark parity example:\n\n```bash\nfullbleed --json render \\\n  --html-str \"<h1>Watermark probe</h1><p>hello</p>\" \\\n  --css-str \"body{font-family:sans-serif}\" \\\n  --watermark-text \"INTERNAL\" \\\n  --watermark-layer overlay \\\n  --watermark-opacity 0.12 \\\n  --watermark-rotation -32 \\\n  --out output/watermark_probe.pdf\n```\n\n## Reference-Image Parity Workflow (Practical)\n\nWhen targeting a design reference image (for example reference image exports), this loop has worked well:\n\n1. Start from `fullbleed init` so CSS/font/icon baselines are vendored and pinned.\n2. For scaffolded projects, run `python report.py` and set `FULLBLEED_IMAGE_DPI` as needed for sharper previews.\n3. For direct CLI template rendering, register assets through the CLI (`--asset ...`) or `AssetBundle`.\n4. Iterate with image artifacts enabled:\n\n```bash\nfullbleed --json render \\\n  --profile preflight \\\n  --html templates/invoice.html \\\n  --css templates/invoice.css \\\n  --asset vendor/css/bootstrap.min.css --asset-kind css --asset-name bootstrap \\\n  --asset vendor/icons/bootstrap-icons.svg --asset-kind svg --asset-name bootstrap-icons \\\n  --asset vendor/fonts/Inter-Variable.ttf --asset-kind font --asset-name inter \\\n  --emit-image output/pages_png \\\n  --emit-jit output/render.jit.jsonl \\\n  --emit-perf output/render.perf.jsonl \\\n  --out output/render.pdf\n```\n\n5. Use `--repro-record` / `--repro-check` once your layout stabilizes.\n\nPractical tips:\n- Compare against full-page exports when available.\n- Keep a fixed preview DPI (for example `144` or `200`) across iterations.\n- Commit PNG baselines for repeatable visual checks.\n\n## Public Golden Regression Suite\n\nLaunch-grade render regression coverage is available under `goldens/` with three fixtures:\n\n- `invoice`\n- `statement`\n- `menu`\n\nGolden contract assets:\n\n- Expected hashes: `goldens/expected/golden_suite.expected.json`\n- Expected PNG baselines: `goldens/expected/png/<case>/<case>_page1.png`\n\nRun against committed expectations:\n\n```bash\npython goldens/run_golden_suite.py verify\n```\n\nRefresh baselines intentionally:\n\n```bash\npython goldens/run_golden_suite.py generate\n```\n\n## Human + AI Operating Mode\n\nRecommended automation defaults:\n\n```bash\nfullbleed --json-only render ...\n```\n\nWhy this is agent-safe:\n\n- For command-execution JSON payloads, `schema` is always present.\n- Parser usage errors (`exit=2`) are emitted by argparse as usage text, not JSON payloads.\n- `ok` indicates success/failure without parsing text.\n- Optional artifacts are explicitly named in `outputs`.\n- Schema introspection is available at runtime (`--schema`).\n\nExample parse loop:\n\n```python\nimport json, subprocess\n\nproc = subprocess.run(\n    [\n        \"fullbleed\", \"--json-only\", \"render\",\n        \"--html\", \"templates/report.html\",\n        \"--css\", \"templates/report.css\",\n        \"--out\", \"output/report.pdf\",\n    ],\n    capture_output=True,\n    text=True,\n    check=False,\n)\n\npayload = json.loads(proc.stdout)\nassert payload[\"schema\"] == \"fullbleed.render_result.v1\"\nassert payload[\"ok\"] is True\nprint(payload[\"outputs\"][\"pdf\"])\n```\n\n## MACHINE_CONTRACT.v1\n\n```json\n{\n  \"schema\": \"fullbleed.readme_contract.v1\",\n  \"package\": \"fullbleed\",\n  \"cli_entrypoint\": \"fullbleed\",\n  \"dev_cli_entrypoint\": \"python -m fullbleed_cli.cli\",\n  \"python_module\": \"fullbleed\",\n  \"json_discriminator\": \"schema\",\n  \"core_commands\": [\n    \"render\",\n    \"verify\",\n    \"plan\",\n    \"debug-perf\",\n    \"debug-jit\",\n    \"run\",\n    \"finalize\",\n    \"inspect\",\n    \"compliance\",\n    \"doctor\",\n    \"capabilities\",\n    \"assets\",\n    \"cache\",\n    \"init\",\n    \"new\"\n  ],\n  \"result_schemas\": [\n    \"fullbleed.render_result.v1\",\n    \"fullbleed.verify_result.v1\",\n    \"fullbleed.plan_result.v1\",\n    \"fullbleed.run_result.v1\",\n    \"fullbleed.inspect_pdf.v1\",\n    \"fullbleed.inspect_pdf_batch.v1\",\n    \"fullbleed.inspect_templates.v1\",\n    \"fullbleed.compose_plan.v1\",\n    \"fullbleed.compliance.v1\",\n    \"fullbleed.capabilities.v1\",\n    \"fullbleed.doctor.v1\",\n    \"fullbleed.assets_list.v1\",\n    \"fullbleed.assets_info.v1\",\n    \"fullbleed.assets_install.v1\",\n    \"fullbleed.assets_verify.v1\",\n    \"fullbleed.assets_lock.v1\",\n    \"fullbleed.cache_dir.v1\",\n    \"fullbleed.cache_prune.v1\",\n    \"fullbleed.init.v1\",\n    \"fullbleed.new_template.v1\",\n    \"fullbleed.new_list.v1\",\n    \"fullbleed.new_search.v1\",\n    \"fullbleed.new_remote.v1\",\n    \"fullbleed.debug_perf.v1\",\n    \"fullbleed.debug_jit.v1\",\n    \"fullbleed.repro_record.v1\",\n    \"fullbleed.error.v1\"\n  ],\n  \"artifact_flags\": [\n    \"--emit-manifest\",\n    \"--emit-jit\",\n    \"--emit-perf\",\n    \"--emit-glyph-report\",\n    \"--emit-page-data\",\n    \"--emit-compose-plan\",\n    \"--emit-image\",\n    \"--image-dpi\",\n    \"--deterministic-hash\",\n    \"--repro-record\",\n    \"--repro-check\"\n  ],\n  \"fail_on\": [\"overflow\", \"missing-glyphs\", \"font-subst\", \"budget\"],\n  \"budget_flags\": [\"--budget-max-pages\", \"--budget-max-bytes\", \"--budget-max-ms\"],\n  \"profiles\": [\"dev\", \"preflight\", \"prod\"],\n  \"pdf_version_default\": \"1.7\",\n  \"known_exit_codes\": {\n    \"0\": \"success\",\n    \"1\": \"command-level validation/operational failure\",\n    \"2\": \"argparse usage error\",\n    \"3\": \"CLI runtime/input error wrapper\"\n  }\n}\n```\n\n## Important Behavior Notes\n\n- `render --json` cannot be combined with `--out -` (stdout PDF bytes).\n- `verify` defaults to stdout PDF unless `--emit-pdf` is provided; for machine mode, use `--emit-pdf <path>`.\n- `--emit-image <dir>` writes per-page PNGs as `<stem>_pageN.png` (stem comes from `--out`/`--emit-pdf`, or `render` when streaming PDF to stdout).\n- 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`.\n- `outputs.deterministic_hash_mode` is `pdf_only` by default and `artifact_set_v1` when image artifacts are emitted.\n- 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.\n- Production target is PDF `1.7`.\n- `run` accepts `--html-str` without requiring `--html`.\n- `init` now scaffolds `COMPLIANCE.md` for project-level release review.\n- `compliance --json` emits machine-readable legal/procurement diagnostics.\n- `--watermark-layer underlay` is accepted as a legacy alias and normalized to `background`.\n- `--emit-manifest` includes a `watermark` object with `text|html|image|layer|semantics|opacity|rotation|enabled`.\n- `--fail-on overflow` is enforced from placement data and may auto-enable internal JIT planning.\n- `--fail-on font-subst` is enforced using missing glyph and fallback diagnostics.\n- `--allow-fallbacks` allows fallback diagnostics to remain informational for `missing-glyphs` / `font-subst` gates while still reporting them in JSON output.\n- `--fail-on budget` requires at least one budget threshold flag.\n- `--repro-check` fails on input/hash drift and lock hash mismatches when lock data is available.\n- 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.\n- `--pdf-profile pdfua1` enables tagged output and PDF/UA-1 identification metadata. Treat verifier/seed traces as machine evidence before making external conformance claims.\n- `argparse` usage errors exit with code `2` and emit usage text (not JSON), even when `--json` is present.\n\n## Related Docs\n\n- Agent workflow guide: `llm.txt`\n- CLI JSON contract quick reference: `cli_schema.md`\n- CLI epoch/spec: `CLI_EPOCH.md`\n- PDF template/XObject composition guide: `docs/pdf-templates.md`\n- Licensing guide: `LICENSING.md`\n- Third-party notices: `THIRD_PARTY_LICENSES.md`\n- Living docs example project: `examples/living_docs_atlas/README.md`\n- Roofing invoice parity example: `examples/roofing_invoice/README.md`\n- Iconography smoke example: `examples/iconography_test/README.md`\n- Public golden regression suite: `goldens/README.md`\n\n## License\n\nFullbleed is licensed under the MIT License (`MIT`). Commercial use,\nmodification, distribution, and use in proprietary software are permitted\nsubject to the notice-preservation requirement in `LICENSE`.\n\nCargo and PyPI metadata both declare `MIT`.\n\n- Copyright notice: `COPYRIGHT`\n- Third-party notices: `THIRD_PARTY_LICENSES.md`\n- Practical licensing guide: `LICENSING.md`\n\nFor license information, please visit `fullbleed.dev` or email `info@fullbleed.dev`.\n\nLicense integrity gate (CI-friendly, no build required):\n\n```bash\npython tools/check_license_integrity.py --json\n```\n",
  "bytes": 59342,
  "sha": "2b42667de58abc76f21519f6d0fa38b51fb3ab1a4e31e29c95426c911e460fa1",
  "repo_slug": "fullbleed-engine/fullbleed-official",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fullbleed_engine_fullbleed_mcp_71f1bcab/readme"
}