Diagnostics de rendu

Lorsqu'une charge utile contient une faute de frappe dans une propriété de style, une valeur invalide, une ressource manquante ou du texte qu'aucune police disponible ne peut rendre, le moteur dégrade gracieusement et continue — le rendu réussit, mais l'élément concerné disparaît. Invisible, sauf pour qui lit les avertissements des journaux serveur.

L'option diagnostics fait remonter chacun de ces événements dans le document rendu lui-même. Le même motif que l'encodeur de code-barres utilise déjà pour les charges invalides (espaces réservés [barcode error: …] en ligne) — étendu aux styles, ressources, polices et commandes canvas.

Exemple en direct

Une fixture avec sept cas de défaillance intentionnels — une faute de frappe de style, une valeur invalide, une référence de style non définie, une image manquante, du texte collé sans couverture de police, une commande canvas malformée, et des fautes de frappe dans les raccourcis en ligne. Des marqueurs apparaissent sous chaque cas ; l'appendice en dernière page les agrège.

Output

Try in Playground →

Template

Data

Comment l'activer

Ajoutez un bloc diagnostics à la racine du document :

{
  "document": {
    "diagnostics": {
      "showInDocument": "appendix",
      "minLevel": "warning"
    },
    "content": [ ... ]
  }
}

Propriété	Type	Défaut	Description
showInDocument	string	"off"	Comment faire remonter les diagnostics : off (abandon silencieux, avertissements de journal uniquement), appendix (tableau agrégé en fin de document), inline (paragraphes-marqueurs directement sous l'élément ayant soulevé chaque problème), both (marqueurs en ligne + appendice).
minLevel	string	"warning"	Sévérité minimale à inclure : info (normalisations bénignes comme le repli de casse), warning (abandons silencieux), error (échecs durs interceptés et ignorés par le moteur).

Le mode off par défaut est réellement gratuit : aucune collecte n'a lieu et le rendu ne porte aucun surcoût de diagnostics. L'activation produit toujours des diagnostics complets — rien d'autre n'est à configurer.

Ce qui est capturé

Chaque défaillance affectant le contenu remonte automatiquement par cette surface — sans instrumentation site par site. La couverture inclut :

• Fautes de frappe de styles — fontSizr: 14 au lieu de fontSize. Capturé en warning.
• Valeurs invalides — textAlign: "sideways", strokeLinecap: "wedge", couleurs inanalysables. Capturé en warning.
• Références à des styles non définis — { "p": "...", "style": "doesNotExist" }. Capturé en warning.
• Ressources manquantes ou non résolues — un chemin d'image qui ne résout vers rien (bloc, [image] en ligne, ou canvas), un fichier de famille de police qui échoue au chargement. Capturé en warning.
• Texte sans couverture de police — du contenu dans une langue qu'aucune police disponible ne peut rendre (par exemple du texte collé dans une écriture hors de la couverture intégrée et des polices déclarées). Le message nomme l'écriture et pointe vers la section fonts du document.
• Échecs de commandes canvas — données de chemin SVG malformées, symbologie de code-barres inconnue, commandes sans valeurs requises.
• Valeurs de raccourcis en ligne — [font, X] nommant une famille non déclarée, couleurs [fontcolor]/[mark] inanalysables, valeurs [fontsize]/[letterspacing]/[align] invalides. Capturé en warning ; le raccourci et la valeur rejetée sont nommés.

Le collecteur déduplique chaque défaillance distincte : un style avec une faute appliqué à 100 paragraphes — ou une police manquante touchée par 50 segments de texte — produit UNE entrée, pas 100. La sévérité est augmentée si la même source signale ensuite un problème plus grave : l'appendice reflète le pire cas.

Format de l'appendice

Quand showInDocument vaut appendix ou both, le moteur ajoute une section « Rendering Diagnostics » en fin de document avec un tableau :

Sévérité	Source	Propriété	Message
WARNING	intentionalTypo	fontSizr	Unrecognized style property 'fontSizr' on style 'intentionalTypo'.
WARNING	styleThatDoesNotExist		Style 'styleThatDoesNotExist' is not defined in the document's styles section.
WARNING	(engine)	missing/thermal-plot.png	Image asset 'missing/thermal-plot.png' could not be resolved; the image was skipped.
WARNING	(engine)	Other	No available font can render Other text — "Բարեւ աշխարհ…" will be missing from the output. Add a font that covers this script to the document's fonts section.

La sévérité est codée par couleur : avertissements en doré foncé, erreurs en rouge brique, info en gris ardoise.

Marqueurs en ligne

Quand showInDocument vaut inline ou both, un paragraphe-marqueur est émis directement sous l'élément qui a soulevé chaque problème — que le problème vienne d'un style nommé ou du moteur (image manquante, texte non couvert, commande canvas). Les éléments n'ont pas besoin de style pour que leurs défaillances remontent :

⚠ intentionalTypo: fontSizr — Unrecognized style property 'fontSizr' on style 'intentionalTypo'.

Chaque défaillance distincte est marquée une seule fois (déduplication), à sa position naturelle dans le flux, pour que les auteurs voient OÙ le problème s'est produit.

Niveaux de sévérité

Niveau	Quand émis	Exemple
info	Normalisation bénigne — valeur d'énumération à casse repliée, alias déprécié résolu, section optionnelle absente.	textAlign: "CENTER" accepté et normalisé en "center".
warning	Abandon silencieux — propriété ignorée ou contenu remplacé par un repli. Le moteur continue.	Propriété inconnue, valeur invalide, ressource non résolue, texte non couvert.
error	Échec dur intercepté par le moteur. Élément ignoré, rendu poursuivi.	Ressource requise manquante, charge de code-barres malformée.

Le minLevel par défaut est warning, donc les normalisations de niveau info restent silencieuses sauf activation explicite.

Rien d'autre ne change

Activer diagnostics ajoute uniquement les marqueurs et l'appendice — le reste du rendu est identique, et la journalisation côté serveur continue exactement comme avant. C'est une surface supplémentaire pour les auteurs, pas un remplacement de la journalisation opérationnelle.

Recommandé pour

• Environnements de création — rendus IDE / bac à sable où les auteurs doivent voir leurs fautes de frappe.
• Validation pré-production — rendu CI de chaque modèle avec showInDocument: "appendix" et un appendice non vide signalé comme échec CI.
• Aperçus de portail client — laisser les auteurs de modèles déboguer leurs propres définitions sans plonger dans les journaux.

NON recommandé pour

• Rendus de production pour clients finaux — l'appendice est une aide à la création, pas du contenu destiné au client. Le défaut off est le bon réglage pour les documents livrés.

Parité des formats

PDF et DOCX rendent la même forme diagnostics avec le même comportement de marqueurs en ligne et d'appendice, et les marqueurs comme l'appendice sont composés par le pipeline de contenu habituel de chaque format — leur mise en forme correspond donc au contenu du corps dans les deux sorties.