Inspect layout state over NextPDF Connect

At a glance

Inspect a document’s layout state during a session so you can make positioning decisions with confidence. preview_layout — re-verified against the server tool registry, where PreviewLayoutTool exposes the protocol name preview_layout — is a read-only, idempotent query. It does not render a PDF, does not advance the cursor, and can be called any number of times. These tools are all Core: create_pdf, set_font, add_text, preview_layout, add_page, and output_pdf.

Install

composer require nextpdf/server

Bind a transport. You do not need a licensed tier.

Conceptual overview

preview_layout returns the page count, current page, page dimensions, margins, and cursor position — the page’s own geometry attributes (ISO 32000-2 §7.7.3.3). Use those values to compute the remaining vertical space:

remaining = page_height - bottom_margin - cursor_y

If remaining is greater than the estimated height of your next block, continue on the current page. Otherwise, call add_page first. Because the call is read-only, it returns a normal response on every transport (PSR-18 §p2).

API surface

Tool	Role	Risk tier
`create_pdf`	Open the session	Safe
`set_font`	Set the active font	Caution
`add_text`	Write text, advance the cursor	Caution
`preview_layout`	Read layout state (no mutation)	Safe
`add_page`	Append a page when space runs out	Caution
`output_pdf`	Render and return the PDF	Approval Required / Review (base64)

The tool catalog is the source of record. The tools available to you depend on the installed tier.

Code sample — Quick start

create_pdf (Letter portrait) → document_id.
set_font (helvetica 14).
add_text ×3 (justified paragraphs).
preview_layout → read page_dimensions, margins, cursor_position.
Compute remaining; if too small, add_page.
add_text (next section).
output_pdf.

Code sample — Production

Call preview_layout before any block when you are not sure it will fit. Treat the returned cursor as accurate for the last write. If you changed the font, margins, or line height since the last add_text, write a short probe and re-query before you rely on the predicted position.

Edge cases & gotchas

Stale cursor after a style change. The reported position reflects the last write, not pending state changes. Re-probe if precision matters.
Destroyed session. preview_layout fails on a destroyed document_id. To inspect the layout after output, set destroy: false on the previous output_pdf.
Empty text or unknown font. Standard input-validation errors apply.

Performance

preview_layout is an inexpensive read. The profile for the produced document is structural.

Security notes

The query is read-only and has no side effect. The returned coordinates are not sensitive, but treat them as session-scoped.

Conformance

Statement	Spec	Clause	reference_id
A page object defines its geometry attributes.	ISO 32000-2	§7.7.3.3
A read-only query returns a normal transport response.	PSR-18	§p2

Commercial context

Not applicable — all tools are Core.

Transport availability

Transport	Available	Notes
MCP (stdio)	Yes	`preview_layout` is a `tools/call`.
REST	Yes	A safe GET-style operation.
gRPC	Yes	Unary; idempotent.

HITL risk tier

preview_layout is Safe (read-only) and never gates. create_pdf is Safe. set_font, add_text, and add_page are Caution. output_pdf is Approval Required, downgraded to Review in base64 mode (HITL risk tiers).

Confirmation gate JSON envelope

Read-only inspection never gates:

{ "allowed": true }