# document_engine/themes/

Catalogue des thèmes visuels applicables à un support (bouton "Utiliser
un modèle" à côté d'Aperçu, voir `templates/document/document_edit.html`
et `static/document/js/document-editor.js`). Décision du 24/09/2026 : le
moteur ne porte QUE contenu et mécanisme — chaque thème est une feuille
de style externe (`static/document/themes/<id>.css`, servie telle quelle)
qui habille les classes FIXES du moteur (`.docPage`/`.docText`/
`.docList`/`.docCard`/`.docBadge`/`.docButton`/`.docImage`/
`.docMinigame`/...), jamais du code qui en changerait la structure. Une
centaine de thèmes est prévue à terme : ce découpage (données de
catalogue + CSS statique, aucun code Python par thème au-delà d'une
entrée de catalogue) est pensé pour rester gérable à cette échelle.

## `DOCUMENT_THEMES: list[dict[str, Any]]`
Un dict par thème : `id` (identifiant stable, utilisé dans les URLs et
persisté via `db.set_document_theme`), `name`, `category`, `description`
(affichage dans la modale), `css_path` (chemin sous `static/`, passé à
`url_for('static', filename=...)`), `font_url` (optionnel, lien Google
Fonts), `seed_pages` (contenu de démonstration — une liste de dicts
`{"vertical_align": "top"|"center"|"bottom", "blocks": [...]}`, voir
`document_engine.replace_document_content` pour la forme exacte de
`blocks`). L'auteur d'un thème est responsable de respecter les règles
structurelles du moteur dans son `seed_pages` (ex. un mini-jeu seul sur
sa page — voir `routes/document/document_element_add.py` — jamais
revérifié automatiquement puisque ce contenu vient du thème, pas de
l'utilisateur ; voir `tests/document/test_document_themes.py` pour la
vérification statique de cette règle sur tout le catalogue).

## `get_document_theme_entry(theme_id: str) -> dict[str, Any] | None`
- **Retour** : l'entrée de `DOCUMENT_THEMES` dont `id == theme_id`, ou
  `None` si aucun thème de ce catalogue ne porte cet id.
- **Exceptions** : aucune.

## `seed_blocks_to_elements(blocks: list[dict[str, Any]]) -> list[dict[str, Any]]`
Convertit une liste de blocs de contenu-seed (`seed_pages[i]["blocks"]`)
en une liste d'éléments "à plat" (id/kind/parent_id/attributes)
directement
exploitable par `document_engine.render_document` — ids synthétiques
NÉGATIFS, jamais persistés. Utilisée UNIQUEMENT pour l'aperçu d'un thème
(voir `routes/document/document_theme_preview.py`, destiné à un
`<iframe>` dans la modale) : ce qui est prévisualisé est ainsi
RÉELLEMENT rendu par le moteur, jamais une image statique ni une
resucée manuelle du CSS. Pour la persistance réelle du contenu, voir
`document_engine.replace_document_content` — qui ne réutilise pas cette
fonction, ayant besoin de vrais ids attribués par la base au fil des
insertions.
- **Retour** : liste d'éléments prête pour `render_document`.
- **Exceptions** : aucune.

## `securite_incendie_seed.py` — contenu du premier thème implémenté

`SECURITE_INCENDIE_SEED_PAGES` : vrai contenu de formation (6 pages —
titre, objectifs, classes de feu, méthode P.A.S.S., évacuation, quiz de
validation à 3 questions), jamais du texte de remplissage. Sert à la
fois de contenu par défaut ("utiliser le contenu du modèle") et de
première validation bout-en-bout du mécanisme de thème.