NextPDF Connect でレイアウト状態を検査する

概要

セッション中にドキュメントのレイアウト状態を検査し、配置を判断できるようにします。preview_layout はサーバーのツールレジストリで再検証済みで、PreviewLayoutTool がプロトコル名 preview_layout として公開しています。これは読み取り専用かつ冪等なクエリです。PDF をレンダリングせず、カーソルを進めることもないため、何度でも呼び出せます。対象ツールはすべて Core です。create_pdf、set_font、add_text、preview_layout、add_page、および output_pdf です。

インストール

composer require nextpdf/server

トランスポートをバインドします。ライセンスティアは不要です。

概念の概要

preview_layout は、ページ数、現在のページ、ページ寸法、余白、カーソル位置を返します。これらはページ自体のジオメトリ属性です（ISO 32000-2 §7.7.3.3）。これらの値から、残りの縦方向スペースを計算します。

remaining = page_height - bottom_margin - cursor_y

remaining が次のブロックの推定高さを上回る場合は、現在のページで書き込みを続行します。そうでない場合は、先に add_page を呼び出します。この呼び出しは読み取り専用であるため、すべてのトランスポートで通常のレスポンスを返します（PSR-18 §p2）。

API サーフェス

ツール	役割	リスクティア
`create_pdf`	セッションの開始	Safe
`set_font`	アクティブなフォントの設定	Caution
`add_text`	テキストの書き込みとカーソルの前進	Caution
`preview_layout`	レイアウト状態の読み取り（変更なし）	Safe
`add_page`	スペース不足時のページ追加	Caution
`output_pdf`	PDF のレンダリングと返却	Approval Required/Review（base64）

ツールカタログが正規のカタログです。利用できるツールは、インストール済みのティアによって異なります。

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

create_pdf（Letter 縦向き）→ document_id。
set_font（helvetica 14）。
add_text ×3（両端揃えの段落）。
preview_layout → page_dimensions、margins、cursor_position を読み取る。
remaining を計算する。小さすぎる場合は add_page。
add_text（次のセクション）。
output_pdf。

コードサンプル — 本番

収まるかどうかが不確かなブロックの前には、必ず preview_layout を呼び出します。返されるカーソルは、直近の書き込み に対して正確なものとして扱います。直近の add_text 以降にフォント、余白、または行の高さを変更した場合は、予測位置に依存する前に短いプローブを書き込んでから再照会してください。

エッジケースと注意点

スタイル変更後の古くなったカーソル。 報告される位置は直近の書き込みを反映し、未適用の状態変更は反映しません。精度が重要な場合は、再度プローブします。
破棄済みのセッション。 preview_layout は、破棄済みの document_id では失敗します。出力後にレイアウトを検査するには、直前の output_pdf で destroy: false を設定します。
空のテキストまたは不明なフォント。 標準の入力検証エラーが適用されます。

パフォーマンス

preview_layout は低コストな読み取り操作です。生成されるドキュメントのプロファイルは structural です。

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

このクエリは読み取り専用であり、副作用はありません。返される座標は機微な情報ではありませんが、セッションスコープの情報として扱ってください。

適合性

ステートメント	仕様	条項	reference_id
ページオブジェクトによるジオメトリ属性の定義	ISO 32000-2	§7.7.3.3
読み取り専用クエリによる通常のトランスポートレスポンス返却	PSR-18	§p2

商用コンテキスト

該当なし — すべてのツールが Core です。

トランスポートの可用性

トランスポート	利用可否	備考
MCP（stdio）	可	`tools/call` としての `preview_layout`
REST	可	安全な GET スタイル操作
gRPC	可	ユナリ、冪等

HITL リスクティア

preview_layout は Safe（読み取り専用）であり、ゲートは設けられません。create_pdf は Safe です。set_font、add_text、および add_page は Caution です。output_pdf は Approval Required であり、base64 モードでは Review にダウングレードされます（HITL リスクティア）。

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

読み取り専用の検査ではゲートは設けられません。

{ "allowed": true }