Connect 経由でページアーティファクトをマークする

概要

このレシピでは、ページネーション用クローム（ランニングヘッダーとフッター、ページ番号、透かし、背景）を Connect トランスポート経由でアーティファクトのマーク付きコンテンツとしてラップします。クロームはページ上に表示されたままですが、構造ツリーおよび支援技術の読み上げ順序からは除外されます。このアーティファクトツールは Enterprise ティア に含まれます。NextPDF は class_exists() プローブでこれを検出し、サーバーとともに nextpdf/premium がインストールされている場合にのみ登録します。サブタイプは型付き列挙型です（Pagination、Layout、Page、Background）。

検証には、PDF/UA-2 に対する結果を報告する Enterprise の標準チェックツールを使用します。合格結果はツール自体によるチェック結果であり、独立した適合性認証ではありません。

インストール

composer require nextpdf/server

tools/list 呼び出しで Enterprise アーティファクトツールが存在することを確認します。詳しくは /connect/tool-catalog/. を参照してください。

概念的な概要

論理構造の一部ではないコンテンツはアーティファクトとしてマークされ、読み上げ順序から除外されます（PDF/UA-2 §8.3）。アーティファクトはページネーション、レイアウト、ページ、または背景のコンテンツであり、実際のコンテンツと区別されます（PDF/UA-2 §8.3）。実際のコンテンツは構造ツリーに反映されますが、アーティファクトは反映されません（PDF/UA-2 §8.2.4）。

このツールは、指定されたサブタイプのアーティファクト用マーク付きコンテンツシーケンスを開きます。対応するクローズの前に発行された描画操作は、すべてその内部にラップされます。

API サーフェス

ツール名は、tools/list で稼働中のレジストリと照合して確認します。正式なカタログは /connect/tool-catalog/. です。このレシピではツール数を再掲しません。

コードサンプル — クイックスタート

Background アーティファクトを開き、透かしを描画してから閉じます。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

コードサンプル — 本番

すべてのオープンをクローズと対にし、ページに孤立したコンテンツがないことを確認します。

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

フッターテキストを描画したら、end-artifact ツールで閉じ、PDF/UA-2 に対する標準チェックを実行します。構造ツリーには本文コンテンツのみが含まれている必要があり、透かしとフッターは除外されていなければなりません。

エッジケースと落とし穴

不明なサブタイプ（たとえば "Header"）は拒否されます。Pagination、Layout、Page、Background のいずれかを渡します。
オープンなしのクローズ は、深さゼロのメッセージでエラーになります。オープンとクローズは必ず対にします。
アーティファクトまたは構造コンテキストの前に描画する と、孤立したコンテンツが生成され、構造ルール違反になります。最初に構造またはアーティファクトのコンテキストを開きます。
ツールが存在しない。 nextpdf/premium がない場合、Enterprise アーティファクトツールは登録されず、呼び出しは未知ツールエラーで失敗します。

パフォーマンス

フロントマターの予算は、ドキュメント上の上限です。アーティファクトのラップによって、計測可能な独立フェーズが追加されることはありません。

セキュリティに関する注記

一般的な Connect トランスポートのガイダンス以外に、該当する事項はありません。

適合性

PDF/UA-2 マッピング

サブタイプ	ユースケース
`Pagination`	ランニングヘッダーとフッター、ページ番号、ナビゲーションクローム
`Layout`	罫線、区切り線、装飾的なボーダー
`Page`	ページ固有の補助（トンボ、見当合わせ）
`Background`	透かし、背景の塗りつぶし、ブランディング

タグ → ISO 32000-2 §14.9 クロスリファレンス

主張	条項	reference_id
非構造コンテンツをアーティファクトとしてマークし、読み上げ順序から除外	PDF/UA-2 §8.3
アーティファクトのサブタイプ: pagination/layout/page/background	PDF/UA-2 §8.3
実際のコンテンツは構造ツリー内にあり、アーティファクトは含まれない	PDF/UA-2 §8.2.4

WCAG 2.2 マッピング

装飾的なクロームを読み上げ順序から除外することは、コンテンツレベルで WCAG 2.2 SC 1.3.1（情報及び関係性）を支えます。

標準チェックの合格結果はあくまでチェック結果であり、適合性認証ではありません。その判定は独立したチェッカーが行います。

商用コンテキスト

アーティファクトツールは Enterprise ティアに含まれ、サーバーとともに nextpdf/premium がインストールされている場合にのみ登録されます。

Connect 固有の事項

トランスポートの可用性（MCP / REST / gRPC）

これらのツールは、MCP tools/call、REST ツールエンドポイント、gRPC サービスのいずれでも、共有ツールエグゼキューターを通じて同じ方法で呼び出されます。

HITL リスクティア

アーティファクトの発行とコンテンツの描画は注意レベルであり、標準チェックは読み取り専用です。いずれもデフォルトでは approval_required ではありません。詳しくは /connect/hitl-risk-tiers/. を参照してください。

確認ゲートの JSON エンベロープ

これらのツールは、オペレーターのオーバーライドによっていずれかが approval_required に引き上げられない限り、ゲートをトリガーしません。エンベロープとワンタイムトークンのコントラクトは /connect/hitl-risk-tiers/. にあります。

Connect 経由でページアーティファクトをマークする

Connect 経由でページアーティファクトをマークする

概要

インストール

概念的な概要

API サーフェス

コードサンプル — クイックスタート

コードサンプル — 本番

エッジケースと落とし穴

パフォーマンス

セキュリティに関する注記

適合性

PDF/UA-2 マッピング

タグ → ISO 32000-2 §14.9 クロスリファレンス

WCAG 2.2 マッピング

商用コンテキスト

Connect 固有の事項

トランスポートの可用性（MCP / REST / gRPC）

HITL リスクティア

確認ゲートの JSON エンベロープ

関連項目