Inspecter l’état de la mise en page avec NextPDF Connect

En bref

Inspecte l’état de la mise en page d’un document pendant la session afin de prendre des décisions de positionnement fiables. preview_layout — vérifié à nouveau dans le registre d’outils du serveur, où PreviewLayoutTool expose le nom de protocole preview_layout — est une requête en lecture seule et idempotente. Elle ne produit pas de rendu PDF, ne fait pas avancer le curseur et peut être appelée autant de fois que nécessaire. Ces outils relèvent tous de Core : create_pdf, set_font, add_text, preview_layout, add_page et output_pdf.

Installation

composer require nextpdf/server

Connecte un transport. Aucun palier sous licence n’est requis.

Aperçu conceptuel

preview_layout renvoie le nombre de pages, la page courante, les dimensions de page, les marges et la position du curseur — autrement dit les attributs de géométrie propres à la page (ISO 32000-2 §7.7.3.3). À partir de ces valeurs, calcule l’espace vertical restant :

remaining = page_height - bottom_margin - cursor_y

Si remaining dépasse la hauteur estimée de ton prochain bloc, continue sur la page courante. Sinon, appelle d’abord add_page. Comme l’appel est en lecture seule, il renvoie une réponse normale sur tous les transports (PSR-18 §p2).

Surface d’API

Outil	Rôle	Niveau de risque
`create_pdf`	Démarrer la session	Sûr
`set_font`	Définir la police active	Prudence
`add_text`	Écrire du texte et avancer le curseur	Prudence
`preview_layout`	Lire l’état de la mise en page (sans mutation)	Sûr
`add_page`	Ajouter une page quand l’espace est épuisé	Prudence
`output_pdf`	Effectuer le rendu et renvoyer le PDF	Approbation requise / Revue (base64)

Le catalogue d’outils fait foi. Les outils que tu peux utiliser dépendent du palier installé.

Exemple de code — Démarrage rapide

create_pdf (Letter portrait) → document_id.
set_font (helvetica 14).
add_text ×3 (paragraphes justifiés).
preview_layout → lis page_dimensions, margins, cursor_position.
Calcule remaining ; si l’espace est insuffisant, add_page.
add_text (section suivante).
output_pdf.

Exemple de code — Production

Appelle preview_layout avant tout bloc dont tu n’es pas sûr qu’il tienne dans la page. Considère le curseur renvoyé comme exact pour la dernière écriture. Si tu as changé la police, les marges ou la hauteur de ligne depuis le dernier add_text, écris un court texte de sonde et interroge de nouveau l’état avant de te fier à la position prédite.

Cas limites & pièges

Curseur périmé après un changement de style. La position indiquée reflète la dernière écriture, et non les changements d’état en attente. Effectue une nouvelle sonde si la précision compte.
Session détruite. preview_layout échoue sur un document_id détruit. Pour inspecter la mise en page après la sortie, définis destroy: false dans l’appel output_pdf précédent.
Texte vide ou police inconnue. Les erreurs standard de validation d’entrée s’appliquent.

Performance

preview_layout est une lecture peu coûteuse. Le profil du document produit est structural.

Notes de sécurité

La requête est en lecture seule et n’a aucun effet de bord. Les coordonnées renvoyées ne sont pas sensibles, mais traite-les comme des données limitées à la session.

Conformité

Énoncé	Spécification	Clause	reference_id
Un objet de page définit ses attributs de géométrie.	ISO 32000-2	§7.7.3.3
Une requête en lecture seule renvoie une réponse de transport normale.	PSR-18	§p2

Contexte commercial

Sans objet — tous les outils relèvent de Core.

Disponibilité par transport

Transport	Disponible	Notes
MCP (stdio)	Oui	`preview_layout` est un `tools/call`.
REST	Oui	Une opération sûre de type GET.
gRPC	Oui	Unaire ; idempotent.

Niveau de risque HITL

preview_layout est Sûr (lecture seule) et ne déclenche jamais de gate. create_pdf est Sûr. set_font, add_text et add_page sont Prudence. output_pdf est au niveau Approbation requise, rétrogradé à Revue en mode base64 (niveaux de risque HITL).

Enveloppe JSON du gate de confirmation

L’inspection en lecture seule ne déclenche jamais de gate :

{ "allowed": true }