Inspeccionar el estado de diseño

De un vistazo

Inspeccionar el estado de diseño de un documento durante la sesión para tomar decisiones de posicionamiento. preview_layout —comprobada de nuevo en el registro de herramientas del servidor, donde PreviewLayoutTool expone el nombre de protocolo preview_layout— es una consulta de solo lectura e idempotente. No renderiza un PDF, no avanza el cursor y se puede llamar tantas veces como sea necesario. Todas estas herramientas son Core: create_pdf, set_font, add_text, preview_layout, add_page y output_pdf.

Instalación

composer require nextpdf/server

Vincular un transporte. No se requiere ningún nivel con licencia.

Descripción conceptual

preview_layout devuelve el número de páginas, la página actual, las dimensiones de la página, los márgenes y la posición del cursor: los atributos de geometría propios de la página (ISO 32000-2 §7.7.3.3). A partir de esos valores, calcular el espacio vertical restante:

remaining = page_height - bottom_margin - cursor_y

Si remaining supera la altura estimada del siguiente bloque, continuar en la página actual. De lo contrario, llamar primero a add_page. Como la llamada es de solo lectura, devuelve una respuesta normal en todos los transportes (PSR-18 §p2).

Superficie de la API

Herramienta	Rol	Nivel de riesgo
`create_pdf`	Abrir la sesión	Precaución
`set_font`	Establecer la fuente activa	Precaución
`add_text`	Escribir texto, avanzar el cursor	Precaución
`preview_layout`	Leer el estado del diseño (sin mutación)	Seguro
`add_page`	Añadir una página cuando se agota el espacio	Precaución
`output_pdf`	Renderizar y devolver el PDF	Aprobación requerida / Revisión (base64)

El catálogo de herramientas es la referencia. Las herramientas disponibles dependen del nivel instalado.

Ejemplo de código — Inicio rápido

create_pdf (Letter vertical) → document_id.
set_font (helvetica 14).
add_text ×3 (párrafos justificados).
preview_layout → leer page_dimensions, margins, cursor_position.
Calcular remaining; si es demasiado pequeño, add_page.
add_text (siguiente sección).
output_pdf.

Ejemplo de código — Producción

Llamar a preview_layout antes de cualquier bloque cuyo ajuste sea incierto. Tratar el cursor devuelto como exacto para la última escritura. Si se cambiaron la fuente, los márgenes o la altura de línea desde la última add_text, escribir una sonda breve y volver a consultar antes de confiar en la posición prevista.

Casos límite y trampas

Cursor obsoleto tras un cambio de estilo. La posición notificada refleja la última escritura, no los cambios de estado pendientes. Volver a consultar si la precisión es importante.
Sesión destruida. preview_layout falla con un document_id destruido. Para inspeccionar el diseño después de la salida, establecer destroy: false en el output_pdf anterior.
Texto vacío o fuente desconocida. Se aplican los errores estándar de validación de entrada.

Rendimiento

preview_layout es una lectura de bajo costo. El perfil del documento generado es structural.

Notas de seguridad

La consulta es de solo lectura y no tiene efectos secundarios. Las coordenadas devueltas no son sensibles, pero deben tratarse como limitadas al ámbito de la sesión.

Conformidad

Declaración	Especificación	Cláusula
Un objeto de página define sus atributos de geometría.	ISO 32000-2	§7.7.3.3
Una consulta de solo lectura devuelve una respuesta de transporte normal.	PSR-18	§p2

Contexto comercial

No aplicable: todas las herramientas son Core.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí	`preview_layout` es un `tools/call`.
REST	Sí	Operación segura de estilo GET.
gRPC	Sí	Unaria; idempotente.

Nivel de riesgo HITL

preview_layout es Seguro (solo lectura) y nunca aplica un gate. create_pdf es Precaución. set_font, add_text y add_page son Precaución. output_pdf es Aprobación requerida, degradado a Revisión en modo base64 (niveles de riesgo HITL).

Envoltorio JSON del gate de confirmación

La inspección de solo lectura nunca aplica un gate:

{ "allowed": true }