Fullbleed PDF Engine

Fullbleed PDF Engine

再利用可能な Python、JavaScript、C# コンポーネント、または HTML/CSS で PDF を作成できます。MIT ライセンスです。

決定論的な Rust エンジンで、請求書、レポート、明細書、可変データの印刷ジョブを作成できます。ネイティブの Rust API、Python パッケージ、またはオプションの JavaScript および .NET 統合を使用できます。Python wheel にはエンジン、フォント、CLI が含まれており、サードパーティの Python パッケージやシステムの PDF スタックは必要ありません。JavaScript パッケージには、Node.js とブラウザーのワーカー向けに WebAssembly エンジンとフォントが含まれています。.NET パッケージには、プロセス内でのレンダリングに使うネイティブライブラリが含まれています。

PDF コンポーネントを試す · ドキュメント · サンプル · PyPI · crates.io · npm · リリースノート · MIT ライセンス

これは Fullbleed の実際の出力です。どちらかのプレビューを開くと PDF を確認できます。または、HTML/CSS、データ、フォント設定を含むデザイン済みサンプルをご覧ください。

HTML/CSS と Python コンポーネントで両方のデザインを比較できます。一致するページ出力と、実行可能なソースのダウンロードも利用できます（オプトインのコンポーネントアルファ版）。

Python でドキュメントを構成する

props、ネストされた子要素、リスト、条件付きコンテンツを使って、再利用可能な関数コンポーネントを作成できます。名前付き要素と Python スタイルのマッピングを使って記述します。

from pathlib import Path
import fullbleed
from fullbleed.ui import Document, Heading, Paragraph, Stack, Strong, component

@component
def Line(label, amount):
    return Paragraph(Strong(label), ": ", amount)

@Document(title="Invoice", styles={"@page": {"size": "A4", "margin": "18mm"}})
def Invoice(customer):
    return Stack(
        Heading("Invoice for ", customer, level=1),
        Line("Design", "$120.00"),
        Line("Review", "$40.00"),
        gap="12pt",
    )

Path("invoice.pdf").write_bytes(Invoice("Maple & Finch").render_pdf(fullbleed.PdfEngine()))

このワークフロー全体は 2.5.25 で利用できます。テキストはエスケープされ、コンポーネントは同じ HTML/CSS 印刷エンジン用にコンパイルされます。コンポーネント作成ガイドに従うか、明示的なフォント、再利用可能な行、有料／未払いの状態、PNG プレビューを備えたデザイン済みのコンポーネント請求書を実行してください。

オプトインの Python コンポーネントアルファ版では、スタイルを持つコンポーネント、名前付きのカスタマイズパーツ、列ベースのテーブル、静的な Bootstrap 5.0.0 コンポーネントが追加されます。スタイルを含めて、または除外して HTML をエクスポートでき、同じドキュメントを PDF としてレンダリングすることもできます。このガイドでは class_name の説明と、実行可能なキットを掲載しています。この API は実験的なものです。明示されているプレリリース版のインストール手順に従ってください。

JavaScript では、関数または JSX/TSX でドキュメントを構成できます。React スターターは、型付きのドキュメントコンポーネントを編集可能なデータ、ライブ PDF プレビュー、ダウンロードに接続します。カスタマイズ用に、コンポーネントとスタイルのソース一式が含まれています。

Python コンポーネントのアルファ版を試す

2.6.0a9 プレリリースでは、PageBand による再利用可能なヘッダーとフッター、および PageNumbers による確定済みのページ値が追加されました。予約されたページ余白で、スタイルや class_name セレクターを含む通常のコンポーネントを使用できます。また、外観を内包するコンポーネント、静的な Bootstrap 5.0.0 キット、スタイルの有無を選べる HTML エクスポートも提供します。この API は fullbleed.ui.experimental にあります。名前や動作は変更される場合があります。仮想環境にアルファ版を明示的にインストールしてください。

python -m pip install --pre "fullbleed==2.6.0a9"

これを order.py として保存し、python order.py を実行してください。

from importlib.resources import files
from pathlib import Path
from fullbleed.ui.experimental import Document, Renderer, Theme, pt, style
from fullbleed.ui.experimental import bootstrap as bs

card = bs.Card(
    bs.Paragraph("Your order has passed its final inspection."),
    title="Ready to ship",
    header="ORDER / 1048",
    footer=bs.Badge("Approved", variant="success"),
).with_parts(title=style(color="#205b47"))

document = Document(card, title="Order summary", lang="en-US",
                    theme=Theme(text=style(font_family="Inter", font_size=pt(11))))
Path("order.html").write_text(document.to_html(include_styles=True), encoding="utf-8", newline="\n")
Path("order.unstyled.html").write_text(document.to_html(include_styles=False), encoding="utf-8", newline="\n")
renderer = Renderer(font_files=[str(files("fullbleed_assets").joinpath("fonts/Inter-Variable.ttf"))])
Path("order.pdf").write_bytes(document.render_pdf(renderer))

class_name はクラス名をそのまま追加します。Bootstrap コンポーネントにはデフォルトのスタイルシートが含まれます。.with_style(...) はルートをカスタマイズし、.with_parts(...) は公開されている内部要素をカスタマイズします。HTML エクスポートを含め、すべての Bootstrap コンポーネントは静的です。Bootstrap の JavaScript は含まれません。

Bootstrap とスタイル設定のガイド、再利用可能なコンポーネントのガイド、またはレポートとカタログをご覧ください。アルファ版のリリース手順書には、リリースのゲートと制限事項が記載されています。未公開のチェックアウトでは、python build_backend/fullbleed_build_backend.py wheel --out dist を使って wheel をビルドし、返されたパスからインストールしてください。通常の pip install fullbleed では、安定版チャンネルが選択されます。

ページバンドとページ番号は、Page(header=PageBand(...), footer=PageBand(...)) を通じて設定します。Common Ground フィールドノートの例では、共有のブランドコンポーネント、スタイル付きのページ番号、3 ページにわたる表を使用しています。API では、レコードごとのページ番号、先頭ページでの非表示、空白ページのポリシーをサポートしています。フィット診断では、予約された余白内に収まることを証明できないコンテンツを特定します。HTML エクスポートでは、明示的なページプレースホルダーとともに、ヘッダーとフッターをそれぞれ 1 つ使用します。これらのコンストラクターには a9 が必要です。以前の a8 wheel には含まれていません。

言語を選択

言語	インストール	作成を始める
Python	python -m pip install fullbleed	Python クイックスタート
Rust	cargo add fullbleed	ネイティブ Rust クイックスタート
Node.js / TypeScript	npm install fullbleed	Node クイックスタート · Next.js PDF ダウンロード
ブラウザー JavaScript	npm install --save-exact [email protected]	PDF コンポーネントと JSX · React スターター · HTML/CSS スターター
C# / .NET	dotnet add package FullBleed.DotNet --version 0.2.0	C# コンポーネントとスタイル · NuGet クイックスタート

現在の JavaScript パッケージは 0.7.1 で、エンジン 2.5.29 をラップしています。これには スタイル付きおよびスタイルなしのコンポーネント HTML エクスポートが含まれます。 ダウンロード可能なコンポーネント請求書と React スターターでは、テスト済みの 0.6.0 の固定バージョンが引き続き使われています。HTML/CSS Node.js クイックスタートと JavaScript、Vue、Next.js のスターターでは 0.5.1 が使われています。これらのスターターの固定バージョンはエンジン 2.5.24 をラップしています。いずれも通常の PDF とプレビューを生成します。Node では fullbleed を、ウェブアプリでは fullbleed/browser をインポートしてください。Node アプリケーションでは、 上限付きレンダリングキュー と、オプションのプロセス分離を利用できます。 FullBleed.DotNet 0.2.0 はエンジン 2.5.22 を使用します。このマネージドライブラリの対象は .NET 8 で、.NET 8、9、10 のアプリケーションで動作します。C# ドキュメントコンポーネント、ネイティブレンダリング、コンパイル済みバインディング、プレビューを備えています。別途提供される CLI アダプターには Python CLI が必要です。 Python パッケージには、コンパイル済み可変データジョブと印刷プロファイルを含む完全な CLI が用意されています。Rust ガイドではネイティブ API を説明しています。

最初の PDF

HTML/CSS プレイグラウンドで、デザイン済みの請求書またはレポートを編集し、実際の PDF をダウンロードしてみましょう。アカウント登録やドキュメントのアップロードは不要で、ブラウザー内でローカルに実行されます。Colab の Python ノートブックを使うことも、ローカルスクリプトから始めることもできます。

Python

Windows、macOS、Linux で Python 3.10～3.14 を使用します。

python -m pip install fullbleed

これを hello.py として保存し、python hello.py を実行します。

from pathlib import Path
import fullbleed

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

invoice.pdf を開いてください。クイックスタートでは、フォント、プレビュー、完全なプロジェクトについて説明しています。実行可能なソースは examples/quickstart/hello.py にあります。

Node.js

Node.js 22 以降を使用します。npm install fullbleed を実行し、これを invoice.mjs として保存してから、node invoice.mjs を実行します。

import { writeFile } from 'node:fs/promises';
import { renderPdf } from 'fullbleed';

const result = await renderPdf({
  html: '<h1>Invoice INV-1042</h1><p>Consulting: USD 1,200.00</p>',
  css: '@page { size: A4; margin: 20mm } h1 { color: #175c52 }',
  previewDpi: 96,
});
await writeFile('invoice.pdf', result.pdf);
await writeFile('invoice.png', result.previews[0]);

invoice.pdf またはその PNG プレビューを開いてください。Node.js クイックスタートには、ダウンロード可能なデザイン済み請求書プロジェクトが含まれています。別途提供される Node パッケージは、ESM、CommonJS、TypeScript に対応しています。アプリケーションのルートで使用する場合は、Next.js スターターをお使いください。

ブラウザー JavaScript

編集可能なブラウザーアプリをお試しください 。請求書やレポートを生成し、HTML/CSSを変更して、PDFをダウンロードできます。 レンダリングはローカルのWeb Workerで実行されます。このスターターは、ドキュメントの 入力データをレンダリングサービスにアップロードしません。

これを基に開発するには、プロジェクト全体をダウンロードしてください。 ZIPを展開し、fullbleed-browser-starterでターミナルを開いて、開発ツール用に Node.js 22.12以降を使用します。

npm ci
npm run dev

Viteが表示するlocalhostのURLを開きます。ブラウザーガイド では、既存のアプリへのfullbleed/browserの追加、ランタイム アセットのHTTPSまたはlocalhost経由での配信、キャンセル、カスタムフォント、静的デプロイについて説明しています。 これは提供された静的なHTML/CSSをレンダリングするものであり、実行中のブラウザーページをキャプチャするものではありません。

Rust

ネイティブRustクイックスタートから始めてください。fullbleedクレートは、Pythonを必要とせず、FullBleed::builder()とrender_to_buffer(...)を公開します。このガイドには、フォントを明示し、PNGプレビューを含む、実行可能な請求書とレポートの例のほか、最新のホスト版Rust APIリファレンスも掲載されています。

C#と.NET

.NET 8、9、または10のプロジェクトにFullBleed.DotNetをインストールし、C#クイックスタートに従ってください。通常のメソッド、LINQの子要素、イミュータブルなスタイルオブジェクトを使ってドキュメントを組み立てられます。コンポーネントガイドでは、WithClass、関連付けられたスタイルシート、インラインの上書きについて説明し、フォントを明示した請求書のダウンロード例を最初から最後まで掲載しています。既存のHTML/CSSテンプレートも引き続きサポートされています。ネイティブレンダリングはPythonやブラウザーのランタイムを必要とせず、Windows x64、Linux x64、Intel搭載macOS、Apple Silicon搭載macOS上の.NETプロセス内で実行されます。

作りたいものに合わせて始めましょう

作りたいもの	まずはこちら
個性的な請求書、レポート、通知書、明細書	フォントとソースを含むデザインショーケース
ネイティブの Rust アプリケーション	Rust のクイックスタートと実行可能なサンプル
Node.js または TypeScript アプリケーション	Node のクイックスタートとデザイン付き請求書プロジェクト
Web アプリケーションのブラウザーで生成する PDF	ブラウザーワーカー SDK、編集可能なデモ、完全なプロジェクト
C# または .NET アプリケーション	NuGet のクイックスタートとデザイン付き請求書
JSON から作成する請求書	検証済みの完全なサンプル
HTML/CSS の編集中に自動で再ビルドする機能（2.5.0+）	監視モードの請求書サンプル
プルリクエストで PDF の変更を検出する機能	レビュー済みのベースラインと CI ワークフローを含むスタンドアロンプロジェクト
FastAPI、Flask、または Django での PDF ダウンロード	実行可能な Web アプリケーションのサンプル
Laravel でキュー処理する PDF 請求書	Blade テンプレート、再試行、非公開ダウンロード（PHP と Python）
Rust と Axum から返す PDF レスポンス	リクエスト制限と編集可能なテンプレートを備えた請求書エンドポイント
AWS Lambda での PDF 生成	ローカルのランタイムチェックを備えた Python コンテナスターター
n8n ワークフローの PDF 添付ファイル	Webhook から PDF を生成するワークフローとローカル Docker キット
pandas DataFrame から作成するスタイル付き PDF レポート	CSV データと検証を含むページ分割レポート
CSV から作成するスタイル付き請求書	Acme 請求書プロジェクト
1 つの PDF 内で使う簡体字中国語と英語	明示的なフォント指定とグリフチェックを備えたバイリンガル請求書
複数ページにわたって流し込まれるレポート	ビジネスレポートのサンプル
アクセシビリティチェックに対応したタグ付き出力	アクセシビリティのワークフロー
1 つのテンプレートから作成する多数の文書	固定レイアウトと再フロー型の可変データのサンプル
印刷プロファイルと PDF/VT のレコード階層	印刷出力と検証範囲
コーディングエージェントまたは MCP との統合	エージェントのセットアップ

生成された PDF とそのソースを見る →

Fullbleed を使う理由

• シンプルなデプロイ： 15 種類のプラットフォーム向けにビルド済みの wheel が用意されており、同梱のワークフローではブラウザーやシステムフォントをインストールする必要がありません。
• 再現可能なドキュメント： 明示的なアセットとメタデータ、決定論的なレンダリング、SHA-256 による再現性チェックを備えています。
• ドキュメントに特化したレイアウト： ページ分割、ヘッダーとフッター、表、テンプレートのオーバーレイ、ページ単位のデータに対応しています。
• 大量処理のワークフロー： テンプレートを一度コンパイルしてから、固定レコードまたはリフローするレコードをバインドできます。測定済みのワークロードと制限事項をご覧ください。
• 検証可能な出力： PDF の検査、PNG プレビュー、構造化された診断情報、プロファイル検証ツールを利用できます。

埋め込みされていない Standard 14 フォントのネイティブプレビューでは、簡潔な同梱アウトライン代替フォントを使用するため、システムフォントがなくても Helvetica、Times、Courier、Symbol、Dingbats の基本的なテキストをレンダリングできます。登録済みおよび埋め込み済みのフォントプログラムが優先されます。フォント解決トレースでは bundled_substitute の結果が示され、ランタイム検出では bundled_standard_font_previews が報告されます。フォントのソース、ライセンス、対応範囲の制限をご覧ください。

Fullbleed は、静的な HTML/CSS をドキュメントのレイアウト言語として使用します。テンプレートについては、CSS の対応範囲と残る不足点をご確認ください。JavaScript やウェブサイトのライブ動作が必要な結果に含まれる場合は、ブラウザーを使用してください。

プロファイルの選択だけでは、標準への適合性は確立されません。リリースの証拠資料には、実施したチェックとその制限事項が記録されています。

サポートと貢献

使い方について質問したり、ドキュメントを共有したりするには、ディスカッションをご利用ください。再現可能なバグや機能の提案については、イシューを作成してください。コントリビューターガイドでは、ローカル環境のセットアップ、テスト、変更を加える場所について説明しています。

Fullbleed が役立った場合は、スポンサーシップ、ドキュメントの作成、役立つ使用例の提供を通じて、メンテナンスを支援してください。スポンサーシップは任意です。Fullbleed は引き続き MIT ライセンスのもとで、無料で利用できます。

エージェントの検出とインテグレーション

エージェントがリリース固有のFullbleedの知識を持つ必要はありません。インストール済みのバイナリは、実際のバージョン、選択範囲、機能、パーサーから導出されたCLIの仕様、結果スキーマ、PDFプロファイル、使用例、制約、Agent Skillのメタデータ、MCPツール、受け入れテストタスクを含む、正規の契約を1つ生成します。

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

コミット済みのfullbleed-agent-contract.json、cli_schema.md、llms.txtは、ビルド済みのwheelから生成されます。CIは、バージョン、コマンド、スキーマ、プロファイル、機能に相違があれば拒否します。実行時のイントロスペクションが引き続き正式な情報源です。

ファーストパーティの、バージョンに依存しないskills/fullbleed/SKILL.mdは、マニュアルの内容を重複させることなく、ツールの選択とレンダリング／プレビュー／診断／検証のループを説明します。これはwheelにバンドルされており、存在しない、または空のエージェントスキルディレクトリにエクスポートできます。

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

また、gh skillを使って、ピン留めされたGitHubリリースからSkillを直接インストールすることもできます。ガイドでは、ソースとバージョンの確認方法を説明しています。レンダリングエンジンはPythonパッケージが提供します。

ツール呼び出しを行うエージェントでは、コアパッケージに依存関係を持たせないため、別途バージョン管理されているアダプターをインストールしてください。

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

stdioサーバーはドキュメントのパスを選択したワークスペース内に制限し、エンジンのすべての操作をインストール済みのFullbleedランタイムに委譲します。セマンティック検索、プロジェクト作成、レンダリング／プレビュー、検査、検証、アセット、固定型／リフロー型のコンパイル済みVDPツールを提供します。依存関係のないコアでは、fullbleed mcp --root .も利用できます。

要求された成果物が、構造化コンテンツから作成する決定論的な印刷ドキュメントである場合はFullbleedを使用してください。任意のライブウェブサイトのスクリーンショットやインタラクティブな状態が成果物として求められている場合は、ブラウザーを使用してください。既存ページのコンテンツ自体を書き換える必要がある場合は、汎用PDFエディターを使用してください。

コールドエージェントテストはfullbleed agent-acceptanceで利用できます。コピーして使える簡潔なワークフローはexamples/agent_workflowsに、アプローチに依存しないベンチマークのひな型はagentdocbenchにあります。

このREADMEは、次の正規の使用ガイドです。

• fullbleed CLI（人間向けのワークフローと、機械／エージェントによる自動化）
• fullbleed Pythonバインディング（PdfEngine、AssetBundle、バッチAPI）

その他のテーマ別リファレンスはdocs/にあります。

• docs/install-non-technical.md（技術に詳しくないユーザー向けのセットアップ手順）
• docs/css-coverage.md（検証済みのCSS対応状況、互換性のステータス、現在の不足項目）
• docs/README.md
• docs/engine.md
• docs/performance-architecture.md
• docs/performance-pass-2026-08-04.md
• docs/python-api.md
• docs/ui-accessibility.md
• docs/cli.md
• docs/pdf-templates.md

得られるもの

• PDF 生成にヘッドレスブラウザーは不要です。
• オプションの SHA256 出力ハッシュに対応した決定論的なレンダリングパイプラインです。
• --repro-record と --repro-check による再現性ワークフローです。
• 本番環境で安定して使用できるデフォルトの出力先は PDF 1.7 です。
• VDP／トランザクション用オーバーレイに対応した、Rust ネイティブの PDF テンプレート合成です。
• 外部 PDF ラスター化ランタイムへの依存なしで、オーバーレイと最終合成出力をネイティブな Rust 画像として出力できます（--emit-image）。
• ページごとの決定論的な合成プランに基づく、機能駆動型のページとテンプレートのバインドです。
• CI と AI エージェント向けの、構造化された JSON 結果スキーマです。
• 明示的なリモート利用のオプトインに対応した、オフライン優先のアセットモデルです。
• リモートプロジェクトテンプレートレジストリのワークフロー（new list、new search、new remote）です。
• 拡張しやすさとカスタムワークフローを重視した、Python ファーストの拡張インターフェースです。
• Python からのレンダリング呼び出しでは、Rust のレンダリング実行中に GIL が解放されます。
• バッチレンダリングと一部の内部処理に対応した、順序を保持する標準ライブラリのワーカープールです。
• 意図的に小さく、ライセンス監査済みの Rust 依存関係グラフを採用し、必須のサードパーティ製 Python ランタイムやビルドパッケージはありません。

並行処理モデル

• Python バインディングのレンダリングメソッドは、Stable ABI ブリッジを通じて Rust の実行中に GIL を解放します。
• 並列バッチ API は、Fullbleed の順序を保持する標準ライブラリのワーカープール（render_pdf_batch_parallel(...) と並列ファイル出力版）を使用します。
• 同じ上限付きワーカー実装は、テーブルレイアウトや JIT ペイント処理など、一部の内部負荷の高い処理にも使用されます。
• すべての単一ドキュメントのレンダリングパスで、エンドツーエンドにすべてのコアが最大限使用されるとは限りません。

2.2 のパフォーマンス

Fullbleed 2.2 は、TrueType グリフの正確なサブセット化を維持しながら、コンパイル済みの固定ジオメトリー可変データバインドを追加しています。5 つの独立したベンチマーク用フィクスチャ全体で、PDF のサイズは 95.5～97.3% 縮小し、通常のウォームレンダリングはリリース済みの 2.0.0 より幾何平均で 2.90 倍高速です。

新しいコンパイル一回型 API は、不変の Q32.32 ディスプレイドキュメントを固定化し、HTML 解析、セレクターマッチング、レイアウト、ページネーション、コマンド計画を再実行することなく、繰り返しリンクできます。順序付きの 1 つの PDF 内で同一のタグなしコピーを作成する場合、CompiledDocument.render_pdf_batch(...) は、コピーされたページ辞書間で各ソースページのコンテンツストリームを共有します。測定では、20 コピーの処理がリリース済みの 2.0.0 のウォームレンダラーより、ページあたりの幾何平均で 200.7 倍高速でした。また、1,000 ページのストレステストでは、304,479～666,622 ページ／秒を維持しました。

2.2 コンパイラーには、固定ジオメトリーの可変データ処理パスが新たに実装されています。6 つのバインドフィールドを持つコンパイル済み請求書では、異なる 100,000 件のレコードを、5 回実行時の中央値で、メモリ上に 283.807 ms でレンダリングしました（352,352 ページ／秒）。フラッシュ済みの 88.1 MB の PDF に直接出力する場合は 295.999 ms でした（337,839 ページ／秒）。一度限りのコンパイル時間 4.168 ms を含めると、ファイルへの直接出力は 333,147 ページ／秒です。ハーネスでは、ページ順の一意な請求書 ID 100,000 件、正確なページ数、解決済みマーカー、決定論的なバイト列、バッファーとファイルの SHA-256 の一致を検証しました。次の手順で再現できます。

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

固定ジオメトリーのスロットは、不変のページ空間変換やクリップ内に保持できます。コンパイラーは、アクティブな座標状態プログラムを一度だけ取り込み、コンパクトな各レコードのオーバーレイで再生します。レイアウトを再実行したり、ページ全体のディスプレイリストを複製したりすることはありません。

Base-14／WinAnsi のスロット描画では、測定済みのバイトパッチ式リンカーを引き続き使用します。登録済みの埋め込みフォントでは、コマンドレベルのオーバーレイプログラムを使用するため、コンパイル済みレイアウト、ページネーション、静的なページストリームを共有したまま、バインドされた各値をシェーピングしてフォントサブセットに含めることができます。上記のスループット値は Base-14 の高速処理パスを示すものであり、登録済みフォントのシェーピングに関する値ではありません。 固定コピーの結果は内容が同一の場合に限られます。可変データの結果は、テキストの描画のみが変わり、ジオメトリのリフローが発生しない場合に限られます。任意の新しい HTML や、サイズが変わるレコードを 200 倍高速に描画できるという主張ではありません。測定結果については docs/performance-pass-2026-08-04.mdを、パック済みベクター IR、型付きバインディング、仮想リンカー、シェーダーのロードマップについては docs/performance-architecture.mdを参照してください。

Fullbleed 2.2.5 では、2.2.4 で導入されたサイズが変わるレコード向けの第 3 のコンパイラレーン、CompiledDocument.render_pdf_reflow_bindings(...)を強化しました。テンプレート DOM を一度だけ解析・復元し、検出された構造フローのバリアントを、ガード付きの固定小数点表示プログラムにコンパイルします。一致するレコードは、それらのプログラムに直接バインドされます。ワーカーは、事前に形状を定めたテキスト/TJ 描画スロット、キャッシュ済みの静的 PDF ページセグメント、ページ単位の Deflate、および 1 つの順序付きリンカーを実行します。明示的に信頼された構造スロットには、data-fb-bind-html="slot"を使用します。コンパイル済みのどのバリアントにも安全に配置できない値については、通常の固定小数点レイアウトを一度実行して、新しいバリアントを追加します。

独立した 1,000 件の異なるレコードを用いたケーススタディでは、ホットな直接ファイル処理における 29 サンプルの中央値は 216.160 ms でした。処理速度は 4,626 レコード/秒、8,096 ページ/秒です。最速の 168.995 ms のサンプルでは、5,917 レコード/秒、10,355 ページ/秒に達しました。出力は正確に 1,750 ページで、500/300/150/50 のリフロー分布となり、24,900 個すべてのマーカーが検証されました。スループット重視で調整した 6,870,320 バイトの PDF は、すべてのサンプルで決定論的でした。コンパクト圧縮設定では、コンパイル済み出力は通常の描画結果ともバイト単位で完全に一致しました。サイズは 5,298,961 バイトで、SHA-256 は bb3c441313a08fb00d3bd15f23a567981f3bbbd550908e3a9fe7a07ca5d7f138です。これはホットなコンパイル済みバリアントでの結果であり、これまでにない構造に対する主張ではありません。最初のバリアント検出描画は 0.509 秒（3,437 ページ/秒）で、セットアップ、バインディング、コンパイル、検出、書き込みを含む完全なコールドジョブは 0.588 秒（2,975 ページ/秒）でした。通常の処理経路と比較したホット時の中央値の高速化は、独立した測定で 43.8 倍でした。

インストール

Python を使うのが初めての方や、新しいマシンをセットアップする方は、docs/install-non-technical.mdから始めてください。

python -m pip install fullbleed

ローカルの wheel からインストールする場合：

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

Rust をインストール済みのソースチェックアウトからインストールする場合、Python のビルドパッケージは不要です：

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

リリース用アーティファクトを決定論的に直接作成するには：

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

プラットフォーム別アーティファクトのポリシー：

• Linux の wheel は、x86-64、x86、ARM64、ARMv7、s390x、ppc64le 向けの manylinux2014 に加え、x86-64、x86、ARM64、ARMv7 向けの musllinux_1_2 に対応しています。
• Windows の wheel は x86-64、x86、ARM64 に対応し、macOS の wheel は Intel と Apple silicon に対応しています。
• CPython の安定 ABI により、各プラットフォームの wheel は Python 3.10 から 3.14 までをサポートします。
• CI では、ネイティブランナーまたは適切な QEMU を使用して、ビルドした各 wheel を対象アーキテクチャにインストールし、動作をテストします。さらに、公開前に x86-64 の manylinux wheel を、サポート対象のすべての Python バージョンでテストします。

Windows と Linux の個別ジョブでは、標準 GIL を使用する Python 3.15.0rc3 をチェックします。これには、Python スイートのテストと、Python 3.10 との PDF/プレビューのバイト単位の比較が含まれます。プレビューのカバレッジとその制限を参照してください。

コマンドのサーフェスを検証するには：

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

60 秒で始める（プロジェクトの基本手順）

プロジェクトのスキャフォールドを初期化します。

fullbleed init .

fullbleed init は Bootstrap（5.0.0）を vendor/css/bootstrap.min.css に、Bootstrap Icons（1.11.3）を vendor/icons/bootstrap-icons.svg に、inter を vendor/fonts/Inter-Variable.ttf に同梱し、ライセンス表記（vendor/css/LICENSE.bootstrap.txt、vendor/icons/LICENSE.bootstrap-icons.txt、vendor/fonts/LICENSE.inter.txt）を書き込み、固定ハッシュを含む assets.lock.json を用意するようになりました。 スキャフォールドされた report.py は、メインのレンダリング前にコンポーネントのマウントをスモーク検証し、output/component_mount_validation.json を出力します（グリフの欠落、実際のページネーションのオーバーフロー、または CSS の未検出シグナルがある場合は、即座に失敗します）。現在のエンジンでは、オーバーフローの判定にはレンダリング時のページネーションが適用されます。保守的な JIT 配置境界は、古いエンジン向けの互換性フォールバックとして引き続き使用されます。 スキャフォールドされるコンポーネントには、再利用可能なレイアウト／コンテンツヘルパー（Stack、Row、Text、テーブル／リストのヘルパー、キーと値の行など）を含む components/primitives.py も加わりました。 各スキャフォールド済みプロジェクトには SCAFFOLDING.md も含まれています。コンポーネントを再構成する前に、まずこちらをお読みください。 また、AGENTS.md も含まれており、他のドキュメントツールを一律に禁止することなく、今後のコーディングエージェントのセッションでも、インストール済みランタイムを優先するドキュメント作成ワークフローを維持できます。

追加のプロジェクトアセットをインストールします（プロジェクトのコンテキストでは、デフォルトで ./vendor/... にインストールされます）。

fullbleed assets install inter --json

Bootstrap の基本設定に関する注記：

• プロジェクトのワークフローでは、デフォルトのスタイル設定の基本として Bootstrap（5.0.0）を対象にしています。
• init の外部で明示的に更新する、または Bootstrap を管理する場合に限り、fullbleed assets install bootstrap --json を再実行してください。

スキャフォールドされたコンポーネントパイプラインを使用してレンダリングします。

python report.py

スキャフォールドされた report.py が生成する想定の成果物：

• output/report.pdf
• output/report_page1.png（またはエンジンの画像 API による同等のページプレビュー）
• output/component_mount_validation.json
• output/css_layers.json

標準の静的 PDF リファレンス：

python examples/canonical_reference/report.py

examples/canonical_reference/ は、コンポーネント構成、レイヤー化された CSS、バンドル済みフォント／SVG、インライン SVG、ラスター画像のデータ URI、リンク付きおよびスタンドアロンの HTML 成果物、PDF 出力、PNG プレビュー、検証レポートを網羅する、スキャフォールド形式のリファレンスです。

プロジェクトのブートストラップテンプレート（fullbleed new）

ローカルのスターターを使用します。

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

レジストリからリモートのスターターを検索します。

fullbleed new list --json
fullbleed new search components --json
fullbleed new remote component-showcase ./my-documents --version 0.1.3 --json

ショーケースには、Northstar の請求書と Common Ground のレポートが HTML/CSS と Python コンポーネントの両方で収録されており、作成者が用意したアクセシブルなコミュニティガイドも含まれています。 対応するデザインでは、データ、フォント、CSS、アートワークを共有しています。インストーラーはソースファイルをコピーしますが、依存関係のインストールやプロジェクトの実行は行いません。各キットの requirements.txt には、テスト済みのコンポーネントのプレリリース版が固定されています。 現在のプレビューガイドに従って別の環境にインストールし、4 ページを比較して、ライブ PDF プレビューを見ながら編集してください。より小規模な構成から始める場合は、テンプレートバージョン 0.1.2 の python-components スターターを選択してください。この小規模なキットでは、テスト済みの a6 ランタイムの固定バージョンが維持されています。

fullbleed new local accessible は、詳しい説明を含むアクセシビリティ優先のスターターで、fullbleed.accessibility ランタイムの機能（エンジン検証ツール、PMR、PDF/UA を対象としたシードチェック、非視覚トレース成果物）を実演します。 fullbleed new local reference は、コンポーネントレイヤー、アセット、PDF/PNG 出力、ページデータ、検証レポートを備えたスキャフォールド済みプロジェクトとして、標準の静的 PDF リファレンスの構成を同梱します。

任意のレジストリ上書き（プライベート／カナリアレジストリ向け）：

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

または：

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

スキャフォールド優先のワークフロー（推奨）

fullbleed init は、単一の大きな HTML テンプレートではなく、コンポーネント優先の作成を想定して設計されています。

一般的なスキャフォールドの構成：

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

推奨される作成方法：

1. まず SCAFFOLDING.md を読み、プロジェクトの規約を確認します。
2. report.py には、コンポジションとデータ読み込みを記述します。
3. 再利用可能なコンポーネントの構成要素は components/primitives.py に記述します。
4. セクションのマークアップは components/header.py、components/body.py、components/footer.py に記述します。
5. コンポーネント固有のスタイルは components/styles/*.css に記述します。
6. ページのトークンとコンポジションのスタイルは styles/tokens.css と styles/report.css に記述します。

推奨される CSS レイヤーの順序：

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

推奨される反復作業の流れ：

1. report.py でデータ読み込みとコンポーネントの props を編集します。
2. components/*.py でコンポーネントのマークアップを編集します。
3. components/styles/*.css と styles/*.css でスタイルを編集します。
4. python report.py を実行します。
5. output/report_page1.png、output/component_mount_validation.json、output/css_layers.json を確認します。

任意のスキャフォールド診断：

• JIT トレースを出力するには FULLBLEED_DEBUG=1 を指定します。
• パフォーマンストレースを出力するには FULLBLEED_PERF=1 を指定します。
• ページデータ JSON を保存するには FULLBLEED_EMIT_PAGE_DATA=1 を指定します。
• プレビュー解像度を上げるには FULLBLEED_IMAGE_DPI=144（またはそれ以上）を指定します。
• CI で検証ゲートを厳格化するには FULLBLEED_VALIDATE_STRICT=1 を指定します。

単発のクイックレンダー（プロジェクトのスキャフォールドなし）

再現性確認用のアーティファクトとともに、インラインの HTML/CSS をレンダリングします。

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

--deterministic-hash はデフォルトで出力 PDF の SHA-256 を書き込みます。--emit-image が有効な場合は、PDF の SHA-256 と順序付きページ画像の SHA-256 ハッシュを組み合わせたアーティファクトセットのダイジェスト（fullbleed.artifact_digest.v1）を書き込みます。JSON 出力には outputs.deterministic_hash_mode（pdf_only または artifact_set_v1）が含まれ、画像を出力した場合は outputs.artifact_sha256 と outputs.image_sha256 も含まれます。

保存済みの記録と照合して再実行し、再現性を検証します。

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

既存の検証レンダーから PNG ページアーティファクトを生成します。

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

コンパイルのみのプラン（レンダーなし）：

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

テンプレートのコンポジション計画（確定書き込みなし）：

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

PDF テンプレートのコンポジション（VDP／トランザクション処理）

ソース PDF に可変データを重ねる場合は、組み込みの Rust テンプレートコンポジションパスを使用してください。

最小限の CLI 自動コンポジションの流れ：

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

コンポジション画像の動作：

• テンプレートの自動コンポジションモードでは、--emit-image の PNG は確定済みの合成ページからラスタライズされ、outputs.image_mode=composed_pdf として報告されます。
• 非コンポジションの render／verify 実行では、--emit-image は outputs.image_mode=overlay_document として報告されます。

最小限の template_binding の例：

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

Python API のコンポジションの流れ：

import fullbleed

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

実運用向けの完全な例については、docs/pdf-templates.md と examples/template-flagging-smoke/ を参照してください。

CLI コマンド一覧

コマンド	目的	JSON Schema
render	オプションで PNG ページ成果物を生成しながら、HTML/CSS を PDF にレンダリングします	fullbleed.render_result.v1
verify	オプションで PDF および PNG を出力する検証用レンダリングパスです	fullbleed.verify_result.v1
plan	入力をマニフェストと警告にコンパイル／正規化します	fullbleed.plan_result.v1
run	Python モジュール／ファイルのエンジンファクトリーを使用してレンダリングします	fullbleed.run_result.v1
inspect pdf	PDF のメタデータと構成の互換性を検査します	fullbleed.inspect_pdf.v1
inspect pdf-batch	複数の PDF をファイルごとのステータスとともに検査します	fullbleed.inspect_pdf_batch.v1
inspect templates	テンプレートカタログのメタデータ／互換性を検査します	fullbleed.inspect_templates.v1
compliance	法務／調達向けのライセンス／コンプライアンスレポートです	fullbleed.compliance.v1
debug-perf	perf JSONL ログを要約します	fullbleed.debug_perf.v1
debug-jit	JIT JSONL ログをフィルタリング／検査します	fullbleed.debug_jit.v1
doctor	ランタイムの機能とヘルスチェックを実行します	fullbleed.doctor.v1
capabilities	コマンド／エンジンの機能を機械可読形式で出力します	fullbleed.capabilities.v1
assets list	インストール済みおよびオプションのリモートパッケージを一覧表示します	fullbleed.assets_list.v1
assets info	パッケージの詳細とハッシュ／サイズを表示します	fullbleed.assets_info.v1
assets install	組み込み／リモートパッケージをインストールします	fullbleed.assets_install.v1
assets verify	パッケージとオプションのロック制約を検証します	fullbleed.assets_verify.v1
assets lock	assets.lock.json を書き込み／更新します	fullbleed.assets_lock.v1
cache dir	キャッシュの場所を表示します	fullbleed.cache_dir.v1
cache prune	古いキャッシュ済みパッケージを削除します	fullbleed.cache_prune.v1
init	プロジェクトのスキャフォールドを初期化します	fullbleed.init.v1
new	スターターテンプレートファイルを作成するか、リモートテンプレートを検索／インストールします	fullbleed.new_template.v1, fullbleed.new_list.v1, fullbleed.new_search.v1, fullbleed.new_remote.v1

任意のコマンド／サブコマンドのスキーマを確認するには：

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

特に重要な CLI フラグ

グローバルなマシンフラグ：

• --json：構造化された結果ペイロードを stdout に出力します
• --json-only：--json と --no-prompts を有効にします
• --schema：スキーマ定義を出力して終了します
• --no-prompts：対話型プロンプトを無効にします
• --config：設定ファイルからデフォルト値を読み込みます
• --log-level error|warn|info|debug：CLI のログ詳細度を制御します
• --no-color：ANSI カラー出力を無効にします
• --version：CLI のバージョンを表示して終了します

レンダリング／検証／計画に関する主要なフラグ：

• 入力：--html、--html-str、--css、--css-str --html は、SVG ドキュメントを直接レンダリングするための .svg ファイルを受け付けます。--html-str は、インラインの SVG マークアップを受け付けます。
• ページ設定：--page-size、--page-width、--page-height、--margin、--page-margins
• エンジンの切り替え：--reuse-xobjects、--svg-form-xobjects、--svg-raster-fallback、--shape-text、--unicode-support、--unicode-metrics
• PDF／準拠性：--pdf-version、--pdf-profile、--color-space、--document-lang、--document-title リリース用ワークフローでは、安定したデフォルトとして --pdf-version 1.7 を使用します。 プロファイルの対象：none、pdfa1a、pdfa1b、pdfa2a、pdfa2b、pdfa2u、pdfa3a、pdfa3b、pdfa3u、pdfa4、pdfa4e、pdfa4f、pdfx4、pdfua1、pdfua2、pdfvt1、wtpdf1r、wtpdf1a、tagged。 エイリアス：a、ua、vt、wt1r、wt1a、pdf/a、pdf/ua、pdf/vt。 出力インテントのメタデータ（--output-intent-identifier|--output-intent-info|--output-intent-components）には、--output-intent-icc が必要です。 pdfx4 と pdfvt1 は PDF 1.6 を強制し、タイトルと明示的な書き込み日付（--timestamp current、固定 UTC 日付、または --timestamp-source SOURCE_DATE_EPOCH）が必要です。 PDF/VT の構成では、レコード階層、--pdf-vt-job、プライベート DPM、保守的な再利用ヒント、独立したリリース検証の境界について説明しています。 python tools/validate_pdf_profiles.py --download-verapdf --install-pdf-oxide --strict-external を実行すると、プロファイルのサンプルを再生成し、inspect/JIT のエビデンスを取得し、決定論的ハッシュを再生し、veraPDF で PDF/A と PDF/UA を検証し、pdf_oxide で PDF/X-4 を検証します。WTPDF プロファイルは veraPDF の wt1r／wt1a で検証され、PDF Declaration のエビデンスも含まれます。pdfa4f は、関連付けられた EmbeddedFiles 名前ツリーを出力してチェックします。pdfvt1 は、解析された DPart グラフ（DPartRoot、DPartRootNode、NodeNameList [/Job /Record /Document]、リーフのページ範囲、ページ /DPart 参照）も出力してチェックします。これには /Start と /End の補足的な複数ページのサンプルも含まれ、粒度の細かいブール値と pdfvt_dpart_graph_valid として報告されます。サードパーティによる PDF/VT 認証には専用の PDF/VT プリフライトツールを使用するか、--pdfvt-cmd "tool --input {pdf}" --pdfvt-version-cmd "tool --version" --require-dedicated-pdfvt を指定して同じハーネスに組み込んでください。
• 透かし：--watermark-text、--watermark-html、--watermark-image、--watermark-layer、--watermark-semantics、--watermark-opacity、--watermark-rotation
• 成果物：--emit-jit、--emit-perf、--emit-glyph-report、--emit-page-data、--emit-compose-plan、--emit-image、--image-dpi、--deterministic-hash
• アセット：--asset、--asset-kind、--asset-name、--asset-trusted、--allow-remote-assets
• プロファイル：--profile dev|preflight|prod
• 失敗ポリシー：--fail-on overflow|missing-glyphs|font-subst|budget
• フォールバックポリシー：--allow-fallbacks（フォールバック診断を保持しますが、missing-glyphs／font-subst のゲートでは失敗しません）
• 再現性：--repro-record <path>、--repro-check <path>
• 予算のしきい値：--budget-max-pages、--budget-max-bytes、--budget-max-ms
• リリースゲート：doctor --strict、compliance --strict --max-audit-age-days <n>

SVG ワークフロー

Fullbleed では、実用的な CLI パスとして次の 3 つで SVG をサポートしています。

• --html <file.svg> による SVG ドキュメントの直接レンダリング
• --html-str "<svg ...>...</svg>" による SVG マークアップのインライン指定
• --asset <file.svg> による SVG アセットの参照（種類は自動的に svg と推定されます）

スタンドアロンの SVG ファイルを PDF に変換します。

fullbleed --json render \
  --html artwork/badge.svg \
  --out output/badge.pdf

SVG マークアップをインライン指定して PDF に変換します。

fullbleed --json render \
  --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>" \
  --out output/inline-svg.pdf

SVG アセットを明示的に登録する HTML テンプレートです。

fullbleed --json render \
  --html templates/report.html \
  --css templates/report.css \
  --asset assets/logo.svg \
  --asset-kind svg \
  --out output/report.pdf

SVG のレンダリング動作を指定するフラグです。

• --svg-form-xobjects / --no-svg-form-xobjects
• --svg-raster-fallback / --no-svg-raster-fallback

配布されている Python ホイールでは svg_raster エンジン機能が有効になっているため、--svg-raster-fallback を使って、SVG のテキスト、フィルター、マスク、foreignObject などの非対応の SVG 構文を、決定論的な画像コンテンツにラスタライズできます。カスタムソースビルドでこのフォールバックパスを通知して使用するには、--features python,svg_raster を含める必要があります。

マシンによる検出：

fullbleed capabilities --json

SVG のサポートメタデータを確認するには、fullbleed.capabilities.v1 の svg オブジェクトを参照してください。engine オブジェクトには、コンパイル済みドキュメント／リフローの利用可否と、呼び出しごとにサポートされる圧縮モードも報告されます。また、コンパイル時の svg_raster ビルド機能と、ネイティブベクター SVG、ラスターフォールバックが必要な SVG、未対応／既知の損失がある SVG 機能の機能マトリックスも報告されます。

画像のサポートマトリックス

リリース時に安全に案内できる画像の機能：

• 直接入力としてサポートされるラスター形式：PNG と JPEG。
• SVG は前述の SVG パイプラインで処理されます。サポートされる場合はネイティブベクターで出力し、svg_raster が有効な場合は、フォールバックのみで対応する機能にラスターフォールバックを使用します。
• サポートされる参照先には、ファイルシステムのパス、登録済みバンドルアセット、file/data URI、<img>、CSS の background-image: url(...)、リストスタイル画像、ウォーターマーク画像が含まれます。
• 直接入力として未対応、またはリリース時に対応を案内していないもの：WebP、GIF、TIFF、AVIF、BMP、アニメーション画像、<picture>、srcset、sizes、密度記述子、ブラウザー方式のレスポンシブ画像選択。
• 決定論的なビルドには、ベンダー管理のローカルアセットまたは登録済みの AssetBundle 入力を推奨します。リモートアセットを使うには、明示的に許可する必要があります。

ページごとのテンプレート（page_1、page_2、page_n）

Fullbleed では、内部的に順序付きのページテンプレートを使用します。ドキュメントでは、次のように捉えるとわかりやすくなります。

• page_1：1 ページ目のテンプレート
• page_2：2 ページ目のテンプレート
• page_n：それ以降のページで繰り返し使うテンプレート

設定の対応関係：

• CLI の --page-margins キー：1、2、... と、任意の "n"（またはエイリアス "each"）。
• Python の PdfEngine(page_margins=...)：同じキー形式。
• 数値で指定されたページがない場合は、基本の margin にフォールバックします。
• 最後に設定されたテンプレートは、残りのページで繰り返し使用されます。

CLI の最小限の例：

{
  "1": {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  "2": {"top": "24mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
  "n": {"top": "30mm", "right": "12mm", "bottom": "12mm", "left": "12mm"}
}

fullbleed --json render \
  --html templates/report.html \
  --css templates/report.css \
  --page-margins page_margins.json \
  --header-each "Statement continued - Page {page} of {pages}" \
  --out output/report.pdf

Python の最小限の例：

import fullbleed

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="12mm",
    page_margins={
        1: {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},  # page_1
        2: {"top": "24mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},  # page_2
        "n": {"top": "30mm", "right": "12mm", "bottom": "12mm", "left": "12mm"} # page_n
    },
    header_first="Account Statement",
    header_each="Statement continued - Page {page} of {pages}",
    footer_last="Final page",
)

注：

• CLI では現在、--header-each / --footer-each（および --header-html-each / --footer-html-each）を利用できます。
• ヘッダー／フッターの first／last バリアント（header_first、header_last、footer_first、footer_last）には、Python API を使用してください。

アセットワークフロー（CLI）

インストール済みおよび利用可能なパッケージを一覧表示します。

fullbleed assets list --available --json

組み込みアセットをインストールします。

fullbleed assets install bootstrap
fullbleed assets install bootstrap-icons
# `@bootstrap` / `@bootstrap-icons` are also supported aliases

PowerShell に関する注意：

• シェルの解析による予期しない動作を避けるため、@ エイリアスは引用符で囲みます（例："@bootstrap"）。

リモートアセットパッケージをインストールします。

fullbleed assets install inter

幅広い Unicode のフォールバックパッケージをインストールします（フォントのペイロードが大きくなります）。

fullbleed assets install noto-sans

カスタムのベンダーディレクトリにインストールします。

fullbleed assets install bootstrap --vendor ./vendor

グローバルキャッシュにインストールします。

fullbleed assets install inter --global

一般的なバーコードフォントをインストールします（ライセンス上安全なデフォルト）。

fullbleed assets install libre-barcode-128
fullbleed assets install libre-barcode-39
fullbleed assets install libre-barcode-ean13-text

ロックファイルと照合し、エラー時に厳密に失敗するよう検証します。

fullbleed assets verify inter --lock --strict --json

ファイルを削除せずに、キャッシュのクリーンアップをプレビューします。

fullbleed cache prune --max-age-days 30 --dry-run --json

注意：

• 組み込みパッケージは、プレーンな参照と@付きの参照の両方を使用できます（bootstrap == @bootstrap、bootstrap-icons == @bootstrap-icons、noto-sans == @noto-sans）。
• noto-sansは組み込みのフォールバックパッケージとして利用できますが、interより意図的にサイズが大きくなっています。ドキュメントでより幅広いグリフのカバー範囲が必要な場合に使用してください。
• プロジェクトのマーカー（CWD 内のassets.lock.json、report.py、またはfullbleed.toml）が存在する場合、プロジェクトへのインストール先はデフォルトで./vendor/になります。
• プロジェクトのマーカーが見つからない場合、--vendorを明示的に指定しない限り、assets installのインストール先はデフォルトでグローバルキャッシュになります。
• %LOCALAPPDATA%/fullbleed/cache/...のようなキャッシュパスをハードコードしないでください。assets install --jsonを使用し、installed_toの値を利用してください。
• インストール済みアセットには、種類別のベンダーディレクトリ（例：vendor/fonts/、vendor/css/）にライセンスファイルが含まれます。
• assets lock --addは現在、組み込みパッケージの追加を対象としています。
• リモートレジストリのバーコードパッケージは、現在 Google Fonts の OFL-1.1 ファミリー（Libre Barcode）です。
• USPS IMB フォントは現在、assets installでは自動インストールできません。審査済みのローカルフォントファイルを使用し、ライセンスは別途管理してください。

Bootstrap のベンダー化

Bootstrap 組み込みパッケージの詳細：

• パッケージ：bootstrap（エイリアス：@bootstrap）
• 同梱バージョン：5.0.0
• アセットの種類：CSS（bootstrap.min.css）
• デフォルトのインストール先：vendor/css/bootstrap.min.css（プロジェクトモード）
• ライセンス：MIT
• ライセンスの取得元：https://raw.githubusercontent.com/twbs/bootstrap/v5.0.0/LICENSE

Bootstrap Icons 組み込みパッケージの詳細：

• パッケージ：bootstrap-icons（エイリアス：@bootstrap-icons）
• 同梱バージョン：1.11.3
• アセットの種類：SVG スプライト（bootstrap-icons.svg）
• デフォルトのインストール先：vendor/icons/bootstrap-icons.svg（プロジェクトモード）
• ライセンス：MIT
• ライセンスの取得元：https://raw.githubusercontent.com/twbs/icons/v1.11.3/LICENSE

Bootstrap に関する注意：

• Bootstrap はベンダー化されており、アセットパイプラインを通じてインストールできます。
• Bootstrap CSS は明示的に指定されたローカルアセット（--asset @bootstrapまたはAssetBundle）として使用されます。外部 HTML の<link rel="stylesheet">は実行経路ではありません。
• Bootstrap の preflight の例はスモークテストの例として引き続き有用ですが、CSS の同等性に関する主張の正規の根拠ではありません。

検証済み CSS カバレッジ

維持管理されているカバレッジの全記述については、docs/css-coverage.mdを参照してください。

マージされたコンポーネントソース（4379bb4）の全コーパス比較では、 1,662 件のケース全体で 1,619 件が PASS、25 件が FAIL、18 件が REFERENCE-DISPUTED と 報告されています。独立実行 では、失敗という結論が維持されています。保存された 5,489 件の出力すべてとすべてのスコアが、 レビュー済みのベースラインと一致しました。alpha 9 のランブック では、新バージョンの適格性確認と公開パッケージの検証が求められています。 この比較は、任意のドキュメントに対する完全な CSS の同等性や適合性を立証するものではありません。 以下に記載する過去の日付の結果は履歴情報であり、現在のゲートではありません。

2026 年 5 月 19 日時点の概要：

• 追跡対象の CSS モジュール：22
• モジュールの状態：22/22 in_progress
• CSS フィクスチャの全レーン：86/86 件のフィクスチャが合格し、603 件のアサーション／描画チェックを実施
• パリティ状態チェック：合格（tools/generate_css_parity_status.py --check --json）
• 正規の検証成果物：_css_working/css_parity_status.json
• 正規の検証成果物：_css_working/tmp/fixture_full_latest.json
• 正規の検証成果物：_css_working/css_broad_coverage_sprint_s14.md

完全にピン留めされた独立 Wheel265 ゲートは、2026年8月9日に、1,662件のフィクスチャのうち 1,642 PASS、 0 FAIL、20 REFERENCE-DISPUTED で完了しました。この名前付きコーパスで判定可能なすべてのフィクスチャにおいて、厳密なパリティは 100% です。参照結果に異議があるものは明示されたままで、実装の合格として再分類されません。より広範なウェブプラットフォームのカバレッジは、docs/css-coverage.md に記載されたモジュールおよび既知のギャップに関する契約の範囲内です。

2026年8月5日に検証されたフロー／再フローの強化では、固定高さのブロック、1列グリッド、カラム方向フレックスの継続スライスを追加し、コンテンツの重複を回避し、回避対象の図の中にあるスタイル付きの空キャプションを保持し、display: contents のグリッド描画フェーズを維持し、位置指定された包含ブロックをアトミックに扱います。独立レビューで対象となった18件の回帰テストクラスターは 18/18 件が合格しました（13件はピクセル単位で完全一致、フロアを超える差の最大値は 0.97030199%）。この対象診断は、外部コーパス全体のレポートに代わるものではありません。

現在検証済みの動作には、広範な静的ドキュメント CSS 領域における、パーサー -> 評価器 -> 計算器 -> レイアウト／描画の包括的なカバレッジが含まれます（値の計算、レイアウトプリミティブ、ページネーション／フラグメンテーションのベースライン、フェーズ1の変換、グラデーション／エフェクトのサブセット。これには、色を先頭に置いたものと色を交互に含む filter: drop-shadow(...)（計算済みの長さを含む）、mm 単位の長さを伴うモダンな rgb() シャドウ色、重複した drop-shadow(...) の色の拒否、省略可能なフィルター関数のデフォルト値、明示的な色および currentColor を使った backdrop-filter: drop-shadow(...) のラスタ描画、モダンな rgb() と mm の描画カバレッジを伴う厳密な box-shadow の長さ／色構文、ぼかした内側エッジのソフトな描画、方向性のある内側オフセットエッジの描画が含まれます。また、オーバーフローを条件とする text-overflow: ellipsis、物理的な最小／最大ボックス制約、横書き（horizontal-tb）の RTL における direction のインライン側インセット／マージン／パディング／ボーダーのマッピング、縦書きモードの direction: rtl におけるインライン側インセットの再マッピング、vertical-rl における論理サイズ／インセット／マージン／パディング／ボーダー／最小・最大制約、vertical-lr における論理サイズ／最小・最大制約／インセット／マージン／パディング／ボーダーの再マッピング、vertical-rl では左方向、vertical-lr では右方向に行が進む基本的な縦書きテキスト列、および決定論的な診断も含まれます）。

最終的なパリティ向上に向けて、既知のギャップのカテゴリを明示的に追跡しています。

• 現在のサブセットを超える、残りの filter／backdrop-filter 関数の対応範囲。SVG url() フィルター、現在の柔軟な色順序に対応した foreground と基本的な backdrop の対応範囲を超える高度な drop-shadow() 形式、PDF ネイティブの foreground フィルターを含みます
• 現在の基本図形サブセットを超える高度な clip-path 文法。SVG クリップソース、SVG 固有のジオメトリボックス、より詳細なエッジ文法を含みます
• plus-lighter の PDF ネイティブとの同等性、およびより深いネストされた合成／分離の対応範囲
• ぼかした内側シャドウのエッジ忠実度の向上
• 現在対応している、サイズ指定されたグラデーションレイヤーの repeat-x／space／round と、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のサブセットを超える、複数レイヤー背景画像の残りのエッジセマンティクス。幅広いラスター混在スタックの組み合わせを含みます
• 現在対応している固定レイアウトの幅ヒント、自動幅、キャプションの配置、無効なキャプション位置の継承に関する処理を超える、テーブルレイアウトのエッジセマンティクスの強化
• 現在の縦書き静的レイアウトと、基本的な折り返しテキスト列の基準を超える、完全な縦書きテキスト／レイアウトフロー

run コマンド（Python ファクトリー連携）

run を使うと、CLI から Python で作成したエンジンインスタンスを利用できます。

report.py：

import fullbleed

def create_engine():
    return fullbleed.PdfEngine(page_width="8.5in", page_height="11in", margin="0.5in")

CLI の呼び出し：

fullbleed --json run report:create_engine \
  --html-str "<h1>From run</h1>" \
  --css templates/report.css \
  --out output/report.pdf

エントリーポイントの形式：

• module_name:factory_or_engine
• path/to/file.py:factory_or_engine

Rust チャートのコンパイル

Rust ベースのビジュアル／ソースフロントエンド向けに、エンジンは ドキュメントコンテキストに基づくチャートコンパイルも提供します。通常の CSS フォント選択とサイズ、プロジェクトフォントに基づく凡例の測定／折り返し、セマンティックテーブル、 および観測可能なレイアウトエラーに対応します。生成された SVG は派生出力であり、オーサリングソースではありません。

Python API クイックスタート

import fullbleed

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="0.5in",
    pdf_version="1.7",
    pdf_profile="none",
    color_space="rgb",
)

html = "<html><body><h1>Invoice</h1><p>Hello.</p></body></html>"
css = "body { font-family: sans-serif; }"

bytes_written = engine.render_pdf_to_file(html, css, "output/invoice.pdf")
print(bytes_written)

AssetBundle を使ってローカルアセットを登録します：

import fullbleed

bundle = fullbleed.AssetBundle()
bundle.add_file("vendor/css/bootstrap.min.css", "css", name="bootstrap")
bundle.add_file("vendor/fonts/Inter-Variable.ttf", "font", name="inter")

engine = fullbleed.PdfEngine(page_width="8.5in", page_height="11in")
engine.register_bundle(bundle)
engine.render_pdf_to_file("<h1>Styled</h1>", "", "output/styled.pdf")

Python API シグネチャ（実行時検証済み）

これらのシグネチャは、インストール済みパッケージに対して inspect.signature(...) を使って検証されています。

PdfEngine コンストラクター：

PdfEngine(
    page_width=None,
    page_height=None,
    margin=None,
    page_margins=None,
    font_dirs=None,
    font_files=None,
    reuse_xobjects=True,
    svg_form_xobjects=False,
    svg_raster_fallback=False,
    unicode_support=True,
    shape_text=True,
    unicode_metrics=True,
    pdf_version=None,
    pdf_profile=None,
    output_intent_icc=None,
    output_intent_identifier=None,
    output_intent_info=None,
    output_intent_components=None,
    color_space=None,
    document_lang=None,
    document_title=None,
    header_first=None,
    header_each=None,
    header_last=None,
    header_x=None,
    header_y_from_top=None,
    header_font_name=None,
    header_font_size=None,
    header_color=None,
    header_html_first=None,
    header_html_each=None,
    header_html_last=None,
    header_html_x=None,
    header_html_y_from_top=None,
    header_html_width=None,
    header_html_height=None,
    footer_first=None,
    footer_each=None,
    footer_last=None,
    footer_x=None,
    footer_y_from_bottom=None,
    footer_font_name=None,
    footer_font_size=None,
    footer_color=None,
    watermark=None,
    watermark_text=None,
    watermark_html=None,
    watermark_image=None,
    watermark_layer="overlay",
    watermark_semantics="artifact",
    watermark_opacity=0.15,
    watermark_rotation=0.0,
    watermark_font_name=None,
    watermark_font_size=None,
    watermark_color=None,
    paginated_context=None,
    jit_mode=None,
    debug=False,
    debug_out=None,
    perf=False,
    perf_out=None,
)

通常／イタリックのファミリー選択と正確なフェイスマッピングについては、 フォントの登録を参照してください。

モジュールのエクスポート：

• PdfEngine
• CompiledDocument
• CompiledFlowCompression
• AssetBundle
• Asset
• AssetKind
• WatermarkSpec(kind, value, layer='overlay', semantics=None, opacity=0.15, rotation_deg=0.0, font_name=None, font_size=None, color=None)
• concat_css(parts)
• vendored_asset(source, kind, name=None, trusted=False, remote=False)
• inspect_pdf(path)
• inspect_template_catalog(templates)
• finalize_stamp_pdf(template, overlay, out, page_map=None, dx=0.0, dy=0.0)
• finalize_compose_pdf(templates, plan, overlay, out, annotation_mode='link_only')
• fetch_asset(url)

PdfEngine のメソッド：

メソッド	戻り値の形式
register_bundle(bundle)	None
compile_pdf(html, css)	CompiledDocument
render_pdf(html, css, deterministic_hash=None)	bytes
render_pdf_to_file(html, css, path, deterministic_hash=None)	int（書き込まれたバイト数）
render_image_pages(html, css, dpi=150)	list[bytes]
render_image_pages_to_dir(html, css, out_dir, dpi=150, stem=None)	list[str]
render_finalized_pdf_image_pages(pdf_path, dpi=150)	list[bytes]
render_finalized_pdf_image_pages_to_dir(pdf_path, out_dir, dpi=150, stem=None)	list[str]
render_pdf_with_glyph_report(html, css)	(bytes, list)
render_pdf_with_page_data(html, css)	(bytes, page_data_or_none)
render_pdf_with_page_data_and_glyph_report(html, css)	(bytes, page_data_or_none, glyph_report_list)
render_pdf_with_page_data_and_template_bindings(html, css)	(bytes, page_data_or_none, template_bindings_or_none)
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)
plan_template_compose(html, css, templates, dx=0.0, dy=0.0)	dict
render_pdf_batch(html_list, css, deterministic_hash=None)	bytes
render_pdf_batch_parallel(html_list, css, deterministic_hash=None)	bytes
render_pdf_batch_to_file(html_list, css, path, deterministic_hash=None)	int
render_pdf_batch_to_file_parallel(html_list, css, path, deterministic_hash=None)	int
render_pdf_batch_to_file_parallel_with_page_data(html_list, css, path, deterministic_hash=None)	(bytes_written, page_data_list)
render_pdf_batch_with_css(jobs, deterministic_hash=None)	bytes
render_pdf_batch_with_css_to_file(jobs, path, deterministic_hash=None)	int

CompiledDocument のメソッド：

メソッド	戻り値の形式
stats()	dict
render_pdf(deterministic_hash=None)	bytes
render_pdf_to_file(path, deterministic_hash=None)	int
render_pdf_batch(copies, deterministic_hash=None)	bytes
render_pdf_bindings(bindings, deterministic_hash=None)	bytes
render_pdf_bindings_to_file(bindings, path, deterministic_hash=None)	int
render_pdf_reflow_bindings(bindings, deterministic_hash=None, *, compression="throughput")	bytes
render_pdf_reflow_bindings_to_file(bindings, path, deterministic_hash=None, *, compression="throughput")	int

コンパイル済みの処理経路では、解析とレイアウトを一度だけ実行します。render_pdf_batch は、タグなしの同一ページコンテンツを仮想化します。固定バインディングメソッドは、列形式の dict[str, list[str]] データを受け取り、静的な描画を共有しながら、レコードごとに異なる固定ジオメトリのテキストオーバーレイを出力します。これらのメソッドでは、スロットキーが完全に一致すること、列の長さが等しくゼロでないこと、テキストがページ内に収まること、およびタグなしのプロファイルを使用することが必要です。Base-14 テキストではダイレクトバイトパッチ経路を使用し、登録済みフォントはコマンドレベルのオーバーレイにシェーピングされます。バインドされた値によって、レイアウトやリフローが実行されることはありません。

リフローバインディングメソッドも同じ完全一致の列の契約を使用しますが、コンパイル済みの解析済み DOM プログラムを実行します。{{slot}} の値はリテラルテキストとして扱われるため、シェーピング、折り返し、ブロックのサイズ変更、ページ数の変更が発生する場合があります。空の要素では、data-fb-bind-html="slot" を指定すると、信頼済みの生成マークアップを使用できます。この場合、値で要素の子要素が置き換えられます。ネイティブワーカーごとに DOM が 1 つ再利用され、レコードの出力は有界キューを介して入力順に連結されます。構造スロットの値は信頼済みマークアップとして解析されるため、信頼できない入力はサニタイズするか、リテラルテキストとして扱われるスカラーの {{slot}} バインディングを使用してください。レンダリングごとに CompiledFlowCompression.Throughput（デフォルト）または CompiledFlowCompression.Compact を選択できます。モードは 1 つのプロセス内で安全に混在させることができます。信頼境界と現在の制限については、docs/python-api.md を参照してください。

deterministic_hash を設定すると、エンジンは PDF の SHA-256 を指定されたファイルパスに書き込みます。 AssetBundle のメソッド：

• add_file(path, kind, name=None, trusted=False, remote=False)
• add(asset)
• assets_info()
• css()

Python の例（スモークテスト済み）

標準的なスキャフォールドのリファレンス：

python examples/canonical_reference/report.py

テキストの透かし＋診断情報：

import fullbleed

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="0.5in",
    pdf_version="1.7",
    watermark_text="INTERNAL",
    watermark_layer="overlay",
    watermark_semantics="artifact",
    watermark_opacity=0.12,
    watermark_rotation=-32.0,
    debug=True,
    debug_out="build/invoice.jit.jsonl",
    perf=True,
    perf_out="build/invoice.perf.jsonl",
)

html = "<h1>Invoice</h1><p>Status: Ready</p>"
css = "h1{margin:0 0 8px 0} p{margin:0}"

written = engine.render_pdf_to_file(html, css, "output/invoice_watermarked.pdf")
print("bytes:", written)

バッチレンダリング＋グリフ／ページデータのチェック：

import fullbleed

engine = fullbleed.PdfEngine(page_width="8.5in", page_height="11in", margin="0.5in")

jobs = [
    ("<h1>Batch A</h1><p>Alpha</p>", "h1{color:#0d6efd}"),
    ("<h1>Batch B</h1><p>Beta</p>", "h1{color:#198754}"),
]

written = engine.render_pdf_batch_with_css_to_file(jobs, "output/batch.pdf")
print("batch bytes:", written)

pdf_bytes, glyph_report = engine.render_pdf_with_glyph_report("<p>Hello</p>", "")
print("glyph entries:", len(glyph_report))

pdf_bytes, page_data = engine.render_pdf_with_page_data("<p>Hello</p>", "")
print("page data available:", page_data is not None)

トランザクションのヘッダー／フッター＋合計

外部テンプレートファイルを使わない、最小限の自己完結型 Python の例です。以下を示します。

• 2 ページ目以降にも引き継がれるヘッダー。
• {sum:items.amount} によるページごとの小計フッターの展開。
• {total:items.amount} による最終ページの総合計フッターの展開。
• 自動化と照合チェックのための構造化された page_data の合計値。

from pathlib import Path
import fullbleed

rows = []
for i in range(1, 121):  # enough rows to force multiple pages
    amount = 10.00 + ((i * 7) % 23) + 0.25
    rows.append(
        f'<tr data-fb="items.amount={amount:.2f}">'
        f"<td>2026-01-{(i % 28) + 1:02d}</td>"
        f"<td>Txn {i:03d}</td>"
        f'<td class="num">${amount:.2f}</td>'
        "</tr>"
    )

html = f"""<!doctype html>
<html>
<body>
  <h1>Monthly Statement</h1>
  <table>
    <thead>
      <tr><th>Date</th><th>Description</th><th class="num">Amount</th></tr>
    </thead>
    <tbody>
      {''.join(rows)}
    </tbody>
  </table>
</body>
</html>
"""

css = """
body { font-family: sans-serif; font-size: 10pt; color: #111; }
h1 { margin: 0 0 8pt 0; }
table { width: 100%; border-collapse: collapse; }
th, td { padding: 4pt; border-bottom: 1pt solid #e1e1e1; }
thead th { background: #f3f6fa; text-transform: uppercase; font-size: 9pt; }
.num { text-align: right; }
"""

engine = fullbleed.PdfEngine(
    page_width="8.5in",
    page_height="11in",
    margin="12mm",
    page_margins={
        1: {"top": "12mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
        2: {"top": "28mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
        "n": {"top": "28mm", "right": "12mm", "bottom": "12mm", "left": "12mm"},
    },
    header_html_each=(
        '<div style="display:flex;justify-content:space-between;border-bottom:1pt solid #d9d9d9;">'
        '<div style="font-weight:bold;">Acme Ledger</div>'
        '<div style="font-size:9pt;color:#444;">Statement Continued - Page {page} of {pages}</div>'
        "</div>"
    ),
    header_html_x="12mm",
    header_html_y_from_top="6mm",
    header_html_width="186mm",
    header_html_height="10mm",
    paginated_context={"items.amount": "sum"},
    footer_each="Subtotal (Page {page}): ${sum:items.amount}",
    footer_last="Grand Total: ${total:items.amount}",
    footer_x="12mm",
    footer_y_from_bottom="8mm",
)

pdf_bytes, page_data = engine.render_pdf_with_page_data(html, css)
Path("output_transactional_minimal.pdf").write_bytes(pdf_bytes)

assert page_data["page_count"] >= 2
assert page_data["totals"]["items.amount"]["value"] == sum(
    p["items.amount"]["value"] for p in page_data["pages"]
)
print("Wrote output_transactional_minimal.pdf")
print("Page count:", page_data["page_count"])
print("Grand total:", page_data["totals"]["items.amount"]["formatted"])

API に関する注意：

• トランザクションの累計（paginated_context）および HTML ヘッダー／フッターの配置（header_html_*、footer_html_*）には、Python の PdfEngine API を使用してください。
• CLI では現在、より単純なケース向けにテキストのヘッダー／フッターを直接指定するフラグ（--header-each、--footer-each）を使用できます。

CLI での透かしの同等機能の例：

fullbleed --json render \
  --html-str "<h1>Watermark probe</h1><p>hello</p>" \
  --css-str "body{font-family:sans-serif}" \
  --watermark-text "INTERNAL" \
  --watermark-layer overlay \
  --watermark-opacity 0.12 \
  --watermark-rotation -32 \
  --out output/watermark_probe.pdf

参照画像との一致を目指すワークフロー（実践編）

デザインの参照画像（たとえば、参照画像のエクスポート）を目指す場合は、次の手順がうまく機能します。

1. fullbleed init から始め、CSS／フォント／アイコンの基盤をベンダー管理し、バージョンを固定します。
2. スキャフォールド済みのプロジェクトでは、python report.py を実行し、プレビューを鮮明にする必要に応じて FULLBLEED_IMAGE_DPI を設定します。
3. CLI からテンプレートを直接レンダリングする場合は、CLI（--asset ...）または AssetBundle を使ってアセットを登録します。
4. 画像アーティファクトを有効にして反復します。

fullbleed --json render \
  --profile preflight \
  --html templates/invoice.html \
  --css templates/invoice.css \
  --asset vendor/css/bootstrap.min.css --asset-kind css --asset-name bootstrap \
  --asset vendor/icons/bootstrap-icons.svg --asset-kind svg --asset-name bootstrap-icons \
  --asset vendor/fonts/Inter-Variable.ttf --asset-kind font --asset-name inter \
  --emit-image output/pages_png \
  --emit-jit output/render.jit.jsonl \
  --emit-perf output/render.perf.jsonl \
  --out output/render.pdf

5. レイアウトが安定したら、--repro-record／--repro-check を使用します。

実践的なヒント：

• 利用できる場合は、ページ全体のエクスポートと比較します。
• 反復作業の間、プレビューの DPI を一定（たとえば 144 または 200）に保ちます。
• 再現可能な視覚チェックのために、PNG のベースラインをコミットします。

公開ゴールデン回帰テストスイート

リリース品質のレンダリング回帰テストが goldens/ に用意されており、次の 3 つのフィクスチャが含まれています。

• invoice
• statement
• menu

ゴールデンコントラクトのアセット：

• 期待されるハッシュ：goldens/expected/golden_suite.expected.json
• 期待される PNG ベースライン：goldens/expected/png/<case>/<case>_page1.png

コミット済みの期待値に対して実行します。

python goldens/run_golden_suite.py verify

意図的にベースラインを更新します。

python goldens/run_golden_suite.py generate

人間＋AI の運用モード

推奨される自動化のデフォルト設定：

fullbleed --json-only render ...

エージェントにとって安全な理由：

• コマンド実行用の JSON ペイロードには、常に schema が含まれます。
• パーサーの使用方法に関するエラー（exit=2）は、JSON ペイロードではなく、argparse による使用方法のテキストとして出力されます。
• ok によって、テキストを解析せずに成功／失敗を判定できます。
• オプションのアーティファクトは outputs に明示的に記載されます。
• スキーマのイントロスペクションは実行時に利用できます（--schema）。

解析ループの例：

import json, subprocess

proc = subprocess.run(
    [
        "fullbleed", "--json-only", "render",
        "--html", "templates/report.html",
        "--css", "templates/report.css",
        "--out", "output/report.pdf",
    ],
    capture_output=True,
    text=True,
    check=False,
)

payload = json.loads(proc.stdout)
assert payload["schema"] == "fullbleed.render_result.v1"
assert payload["ok"] is True
print(payload["outputs"]["pdf"])

MACHINE_CONTRACT.v1

{
  "schema": "fullbleed.readme_contract.v1",
  "package": "fullbleed",
  "cli_entrypoint": "fullbleed",
  "dev_cli_entrypoint": "python -m fullbleed_cli.cli",
  "python_module": "fullbleed",
  "json_discriminator": "schema",
  "core_commands": [
    "render",
    "verify",
    "plan",
    "debug-perf",
    "debug-jit",
    "run",
    "finalize",
    "inspect",
    "compliance",
    "doctor",
    "capabilities",
    "assets",
    "cache",
    "init",
    "new"
  ],
  "result_schemas": [
    "fullbleed.render_result.v1",
    "fullbleed.verify_result.v1",
    "fullbleed.plan_result.v1",
    "fullbleed.run_result.v1",
    "fullbleed.inspect_pdf.v1",
    "fullbleed.inspect_pdf_batch.v1",
    "fullbleed.inspect_templates.v1",
    "fullbleed.compose_plan.v1",
    "fullbleed.compliance.v1",
    "fullbleed.capabilities.v1",
    "fullbleed.doctor.v1",
    "fullbleed.assets_list.v1",
    "fullbleed.assets_info.v1",
    "fullbleed.assets_install.v1",
    "fullbleed.assets_verify.v1",
    "fullbleed.assets_lock.v1",
    "fullbleed.cache_dir.v1",
    "fullbleed.cache_prune.v1",
    "fullbleed.init.v1",
    "fullbleed.new_template.v1",
    "fullbleed.new_list.v1",
    "fullbleed.new_search.v1",
    "fullbleed.new_remote.v1",
    "fullbleed.debug_perf.v1",
    "fullbleed.debug_jit.v1",
    "fullbleed.repro_record.v1",
    "fullbleed.error.v1"
  ],
  "artifact_flags": [
    "--emit-manifest",
    "--emit-jit",
    "--emit-perf",
    "--emit-glyph-report",
    "--emit-page-data",
    "--emit-compose-plan",
    "--emit-image",
    "--image-dpi",
    "--deterministic-hash",
    "--repro-record",
    "--repro-check"
  ],
  "fail_on": ["overflow", "missing-glyphs", "font-subst", "budget"],
  "budget_flags": ["--budget-max-pages", "--budget-max-bytes", "--budget-max-ms"],
  "profiles": ["dev", "preflight", "prod"],
  "pdf_version_default": "1.7",
  "known_exit_codes": {
    "0": "success",
    "1": "command-level validation/operational failure",
    "2": "argparse usage error",
    "3": "CLI runtime/input error wrapper"
  }
}

重要な動作上の注意事項

• render --json と --out -（標準出力へのPDFバイト列の出力）は併用できません。
• verify は、--emit-pdf を指定しない場合、PDFを標準出力に出力します。機械処理モードでは、--emit-pdf <path> を使用してください。
• --emit-image <dir> は、ページごとのPNGを <stem>_pageN.png として書き出します（stem は --out／--emit-pdf の値から取得するか、PDFを標準出力にストリーミングする場合は render になります）。
• テンプレートの自動合成を行う実行では、--emit-image の成果物は合成済みの最終ページからラスタライズされ、outputs.image_mode=composed_pdf と報告されます。それ以外の場合、image_mode=overlay_document になります。
• outputs.deterministic_hash_mode は、デフォルトでは pdf_only、画像の成果物が出力される場合は artifact_set_v1 です。
• --emit-page-data と --emit-glyph-report の両方が指定されている場合、現在のエンジンではAPIを統合して1回だけレンダリングします。このAPIに対応していない古いエンジンでは、2回レンダリングする方式にフォールバックします。
• 本番環境のターゲットはPDF 1.7 です。
• run では、--html を指定しなくても --html-str を使用できます。
• init は、プロジェクト単位のリリースレビュー用に COMPLIANCE.md も生成するようになりました。
• compliance --json は、機械可読形式の法務・調達診断情報を出力します。
• --watermark-layer underlay はレガシーエイリアスとして受け付けられ、background に正規化されます。
• --emit-manifest は、text|html|image|layer|semantics|opacity|rotation|enabled を含む watermark オブジェクトを出力します。
• --fail-on overflow は配置データに基づいて適用され、内部のJIT計画が自動的に有効になる場合があります。
• --fail-on font-subst は、欠落グリフおよびフォールバック診断を使用して適用されます。
• --allow-fallbacks を指定すると、missing-glyphs／font-subst ゲートにおけるフォールバック診断は情報提供扱いのままになりますが、JSON出力には引き続き報告されます。
• --fail-on budget を使用するには、少なくとも1つの予算しきい値フラグが必要です。
• --repro-check は、ロックデータが利用可能な場合、入力／ハッシュの差異やロックハッシュの不一致があると失敗します。
• PDF/AおよびPDF/X/VTプロファイルでは出力インテントのメタデータが必要です。pdfa4、pdfa4e、pdfa4f はPDF 2.0を自動的に出力します。PDF/A、PDF/X/VT、PDF/UA、WTPDFのテキスト出力ではフォント埋め込みの制約が適用され、CLIエラーには埋め込み可能なフォントアセットを追加するための具体的なヒントが含まれます。
• --pdf-profile pdfua1 を指定すると、タグ付き出力とPDF/UA-1識別メタデータが有効になります。外部に適合性を表明する前に、検証器／シードのトレースを機械的な証拠として扱ってください。
• argparse の使用方法エラーは終了コード 2 で終了し、--json が指定されていても、JSONではなく使用方法のテキストを出力します。

関連ドキュメント

• エージェントのワークフローガイド：llm.txt
• CLI JSON契約クイックリファレンス：cli_schema.md
• CLIエポック／仕様：CLI_EPOCH.md
• PDFテンプレート／XObject合成ガイド：docs/pdf-templates.md
• ライセンスガイド：LICENSING.md
• サードパーティ通知：THIRD_PARTY_LICENSES.md
• 生きたドキュメントのサンプルプロジェクト：examples/living_docs_atlas/README.md
• 屋根工事請求書の同等性サンプル：examples/roofing_invoice/README.md
• アイコノグラフィのスモークテストサンプル：examples/iconography_test/README.md
• 公開ゴールデン回帰テストスイート：goldens/README.md

ライセンス

Fullbleed はMITライセンス（MIT）の下でライセンスされています。商用利用、変更、配布、およびプロプライエタリソフトウェアでの使用は、LICENSE に定められた通知保持要件に従う限り許可されています。

CargoとPyPIのメタデータには、どちらも MIT と記載されています。

• 著作権表示：COPYRIGHT
• サードパーティ通知：THIRD_PARTY_LICENSES.md
• 実践的なライセンスガイド：LICENSING.md

ライセンス情報については、fullbleed.dev をご覧いただくか、[email protected] までメールでお問い合わせください。

ライセンス整合性ゲート（CI対応、ビルド不要）：

python tools/check_license_integrity.py --json