From 46515d0459afb196b76d0215bd7c36711d7309b9 Mon Sep 17 00:00:00 2001
From: Nabil Derouiche <contact@bolbol.tn>
Date: Sun, 14 Jun 2026 15:51:40 +0100
Subject: [PATCH] common: runbook Gotenberg HTML->PDF (piege police web,
 waitDelay)

---
 _INDEX.md               |  1 +
 common/gotenberg-pdf.md | 25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 common/gotenberg-pdf.md

diff --git a/_INDEX.md b/_INDEX.md
index c86874f..2a5e2d4 100644
--- a/_INDEX.md
+++ b/_INDEX.md
@@ -11,6 +11,7 @@
 |---------|------|------|
 | [Acces Bifrost (passerelle LLM, vision/OCR)](common/bifrost-access.md) | 2026-06-14 | infra, bifrost, llm, vision, x-bf-vk |
 | [Generation / edition d'images IA (nano-banana)](common/openrouter-image-gen.md) | 2026-06-14 | infra, openrouter, image, nano-banana |
+| [Gotenberg HTML->PDF (piege police web)](common/gotenberg-pdf.md) | 2026-06-14 | infra, gotenberg, pdf, fonts |
 
 ## hermes-perso
 | Runbook | Date | Tags |
diff --git a/common/gotenberg-pdf.md b/common/gotenberg-pdf.md
new file mode 100644
index 0000000..2685738
--- /dev/null
+++ b/common/gotenberg-pdf.md
@@ -0,0 +1,25 @@
+# GOTENBERG-PDF — HTML → PDF (piège police web)
+
+Note partagée aux 3 instances Hermes. Source : projet gsparc-mezzouna, 2026-06-14.
+
+Gotenberg convertit du HTML en PDF. Conteneur `gotenberg` sur le réseau **n8n**, port **3000**.
+`POST http://gotenberg:3000/forms/chromium/convert/html` (champ `files` = index.html).
+
+## PIÈGE — police web manquante sur pages lourdes
+Sur une page **lourde** (grosse image base64 en ligne), Chromium **imprime avant que la police web** (`@import` Google Fonts) soit appliquée → **texte manquant ou rendu incohérent** d'un document à l'autre. C'est **déterministe selon le poids** : les pages légères passent, les lourdes échouent (piège : on croit à un aléa).
+
+## SOLUTION
+- Champ form **`waitDelay: "1.5s"`** → laisse charger les ressources async (police) avant impression.
+- **Alléger** la page : redimensionner les images embarquées.
+- Pile de polices de secours avec une Arabe quasi toujours présente dans Chromium :
+  `font-family: Cairo,"Noto Sans Arabic","Noto Naskh Arabic",Tahoma,Arial,sans-serif;`
+
+## Exemple (paysage A4 pleine page)
+```bash
+curl -s http://gotenberg:3000/forms/chromium/convert/html \
+  -F "files=@index.html" \
+  -F "paperWidth=11.69" -F "paperHeight=8.27" \
+  -F "marginTop=0.2" -F "marginBottom=0.2" -F "marginLeft=0.2" -F "marginRight=0.2" \
+  -F "landscape=true" -F "printBackground=true" -F "waitDelay=1.5s" -o out.pdf
+```
+Implémentation de référence : `gsparc-mezzouna/app/routes/export.py` (`_fiche_pdf_bytes`).